Website Connector Starter Pack + Verification Guide

Guide

A starting point for your developer

Connecting your website does not mean you need to build the integration yourself. You can hand this pack to your developer or agency and work through the checks together. It gives them a small order example, a verification checklist, and the security details that must not be skipped.

This is a developer and agency starter/reference pack, not an installable plugin or a finished connector. Your developer still needs to map your checkout events, build the sender, and verify the result with your own website. Keep the Website API reference alongside it.

Start with one controlled example

1. Open Website setup from Control Centre and obtain the Website API key and signing secret. Keep both in server-side secret storage, never browser code.
2. Download the v2 created-order JSON example. Its order reference and SKU are fictional: replace them with a unique test order reference and an existing SKU in the connected account's test stock.
3. Map created orders to POST /webhooks/website/orders/created. The JSON object needs top-level external_order_ref, currency_code, and line_items; do not wrap it inside an order object. Each line needs an existing sku and a positive quantity.
4. Use a controlled test environment. The example has a zero unit price, but a £0 order is not a dry run: the order endpoint uses normal order and stock workflows. Agree the test stock and any downstream effects before sending.
5. Check the HTTP response, the Website order in ChannelWeave, and the resulting stock availability. Then test cancellation and a repeated delivery before allowing real checkout traffic.

Created and cancelled orders are different requests

The JSON download is for orders/created only. For POST /webhooks/website/orders/cancelled, send the same order reference and transaction currency; lines are not required:

{
  "external_order_ref": "TEST-WEB-ORDER-001",
  "currency_code": "GBP"
}

Use the actual transaction currency, not a default chosen by the connector. Cancellation can release existing stock reservations, so include it in the controlled test plan rather than trying it on a real customer's order.

Keep the security controls together

Order webhooks require all three headers:

• Authorization: Bearer <website_api_key>
• X-CW-Timestamp: <current Unix time in whole seconds>
• X-CW-Signature: v1=<hmac_sha256_hex>

Compute HMAC-SHA256 with the Website signing secret over the timestamp header, a full stop, and the unchanged UTF-8 JSON request body: timestamp.raw_body. Send exactly the body you signed; re-serialising JSON afterwards changes the signature. ChannelWeave rejects timestamps more than 300 seconds (five minutes) away from its current time. Keep the sender's clock accurate.

Catalogue and stock reads use the Website bearer token only; do not confuse their authentication with signed order webhooks. Plan and test credential rotation with your developer: the current rotation flow gives the previous API key or signing secret a 24-hour overlap. Update the sender and verify the new credential before the old one expires.

Retries and stock caching

• Keep the same external_order_ref and line ordering when retrying an unchanged created order. Repeated deliveries update the existing order; they are not a general promise of exactly-once processing.
• Generate a fresh timestamp and signature for each retry. An X-CW-Idempotency-Key can help correlate order diagnostics, but it is not a replacement for the order reference or duplicate-delivery testing.
• Your sender needs bounded retries and a visible failed-delivery record. Order ingestion is immediate; do not assume ChannelWeave queues failed incoming requests for you.
• On your website or relay, serve dynamic stock responses with Cache-Control: no-store, bypass CDN edge caching, and disable stale-while-revalidate for inventory quantities. Verify the actual response headers and CDN rules rather than assuming they are already configured.

What the downloads cover

The v2 verification checklist is a handoff and test record for your developer. The v2 created-order JSON example illustrates the current request shape; it contains no credentials or real customer data. Neither file certifies a connector as ready for production. Start small, record what happened, and resolve failed checks before switching on real orders.