Website webhooks

Contracts for Website order/contact webhook ingestion and outbound Website reply dispatch.

Last updated:

Order webhook routes

  • POST /webhooks/website/orders/created
  • POST /webhooks/website/orders/cancelled

Auth and integrity headers

  • Authorization: Bearer <website_api_key>
  • X-CW-Timestamp
  • X-CW-Signature (v1=<hmac_sha256_hex>)

Required request body fields

{
  "external_order_ref": "WEB-10001234",
  "line_items": [
    {
      "sku": "ABC-001",
      "quantity": 2
    }
  ]
}

For orders/cancelled, only external_order_ref is required.

When POST /webhooks/website/orders/created is called:

  • ChannelWeave creates/updates the website order record immediately.
  • line_items are created/updated by line number.
  • All line sku values must exist in tenant stock.
  • Order totals are recalculated from order lines plus shipping_*/discount_amount.

When POST /webhooks/website/orders/cancelled is called:

  • Order status and fulfilment status are set to cancelled.
  • Existing order lines are marked cancelled.

Optional order/buyer/address fields

Optional fields are upserted when provided:

  • external_order_number
  • currency_code (defaults to GBP)
  • order_date, external_created_at, external_updated_at
  • payment_status (defaults to account_pending)
  • shipping_net_amount, shipping_tax_amount, discount_amount
  • buyer_name, buyer_email, buyer_phone
  • shipping_address
  • billing_address

shipping_address and billing_address accept either direct address objects or nested shipping.address and billing.address objects.

Address data is normalised into:

  • the order shipping address field
  • the order billing address field

line_items contract

Each line_items[] entry accepts:

  • sku (required)
  • quantity (required, positive number)
  • unit_price or price (optional, non-negative)
  • discount_amount, tax_rate, tax_amount, net_amount, gross_amount (optional)
  • external_line_ref, line_ref, id (optional idempotency reference)
  • external_item_ref, item_ref, listing_id (optional)
  • description/title/name (optional description text)

Contact-message webhook route

  • POST /webhooks/website/messages/contact

Purpose

Accepts website contact-form submissions and creates/updates an Inbox → Messages conversation with:

  • channel_code = 'website'
  • message_type_code = 'buyer_question'
  • direction = 'inbound'

Request contract

Content type: JSON object (application/json).

Required auth and integrity headers:

  • Authorization: Bearer <website_api_key>
  • X-CW-Timestamp
  • X-CW-Signature (v1=<hmac_sha256_hex>)

Required fields:

  • name
  • email
  • message
  • submission_id (or X-CW-Idempotency-Key header)

Optional fields:

  • company
  • target_date (YYYY-MM-DD)
  • website_host
  • website_domain
  • source_url
  • page_url
  • website_url

For static websites, the browser should post to your own relay endpoint first; the relay signs and forwards JSON to this ChannelWeave route.

Response codes

  • 200 { "ok": true } on ingest
  • 401 missing/invalid API key
  • 400 bad signature/timestamp or invalid payload
  • 500 server error

Outbound Website reply dispatch (customer relay)

When an operator replies to an eligible Website conversation in Inbox → Messages, ChannelWeave sends a signed server-to-server POST to the customer website relay:

  • POST https://<customer-website>/api/website/replies/send

Required integrity headers:

  • X-CW-Timestamp
  • X-CW-Signature (v1=<hmac_sha256_hex>)
  • X-CW-Idempotency-Key

Required JSON fields:

  • reply_id
  • thread_id
  • buyer_email
  • subject
  • reply_body

Recommended optional JSON fields:

  • buyer_name
  • external_thread_id
  • sent_at

Relay expectations:

  • verify timestamp window + signature using Website signing secret
  • enforce idempotency by reply_id / idempotency header
  • deliver the email via the customer’s configured provider
  • return 200 { "ok": true } when delivery succeeds