Order webhooks - Chataigne Docs

Order webhooks notify a POS receiver or observer without requiring polling. Configure endpoints during integration onboarding or from the Webhooks dashboard when access is enabled for your account.

Events

Event	Payload	Typical use
`order.created`	Complete current public order snapshot	Create the order in the POS
`order.status.updated`	Current status, `status_version`, fulfillment times, previous status, source, and reason	Reconcile bidirectional state

Chataigne persists the event and the business change in the same database transaction before queueing delivery. BullMQ transports the persisted delivery; it is not the source of truth.

Endpoint routing

An endpoint can be an observer or the primary order receiver.

A location endpoint has priority over an organization endpoint for the same event.
If no location observer subscribes, organization observers are used as fallback.
The effective primary receiver is the location receiver when present, otherwise the organization receiver.
Exactly one primary receiver receives each order event for a location.
A synchronous POS integration and an API receiver can both be active. Chataigne sends order events to both; restaurant operators are responsible for configuring downstream systems so they do not create duplicate operational orders.
Observer endpoints can subscribe in parallel for analytics and other non-operational use cases.

Event envelope

{
  "id": "evt_01J...",
  "object": "event",
  "type": "order.created",
  "api_version": "v1",
  "created_at": "2026-08-07T10:00:00.000Z",
  "data": {
    "object": {
      "id": "order_01J...",
      "object": "order",
      "short_id": "A-042",
      "status": "received",
      "status_version": 0
    }
  }
}

Deduplicate by event id, not order id. Store the event identifier before performing side effects, then return any 2xx response. Repeated delivery of the same event must be a no-op.

Verify the signature

Each request includes:

Chataigne-Event-Id
Chataigne-Timestamp as Unix seconds
Chataigne-Signature: v1=<hex HMAC>

Compute HMAC-SHA256 with your endpoint secret over the exact UTF-8 bytes:

Chataigne-Timestamp + "." + raw_request_body

Compare the hexadecimal digest using a constant-time function. Reject timestamps outside your replay window, then deduplicate Chataigne-Event-Id. Always verify the raw body before JSON parsing; re-serializing JSON changes the signature.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyWebhook({ secret, timestamp, rawBody, signature }) {
  const expected = `v1=${createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')}`;
  const received = Buffer.from(signature);
  const wanted = Buffer.from(expected);
  return received.length === wanted.length && timingSafeEqual(received, wanted);
}

The signing secret is displayed once at endpoint creation or rotation. Store it in a secret manager. Rotating it invalidates the previous secret immediately.

Delivery and retries

Delivery is at least once. Chataigne treats any 2xx as success. HTTP 408, 425, 429, 5xx, timeouts, and network failures are retried up to seven attempts with exponential backoff starting at five seconds. Other 4xx responses are terminal. The durable recovery pass requeues pending deliveries and resets processing claims that have been stale for two minutes. A terminal delivery failure is visible in the delivery log and triggers an operational alert; it never cancels or refunds the order automatically. Use the dashboard to send a synthetic test event, inspect attempts, rotate a signing secret, disable an endpoint, or manually retry a terminal delivery. Returning 2xx means “received”, not “accepted”; send a status update separately when the POS has made its business decision.

Security and retention

Production endpoint URLs must use HTTPS. Chataigne does not follow redirects and validates the resolved destination at connection time to reject loopback, link-local, private, reserved, and metadata-network addresses. Webhook payloads can contain customer contact and address data. Terminal event payloads are redacted after seven days, and terminal event records are deleted after 30 days. A customer erasure redacts retained payloads immediately and cancels any delivery that has not already been claimed for processing. Keep your own copy only for the period required by your contract and applicable law.

​Events

​Endpoint routing

​Event envelope

​Verify the signature

​Delivery and retries

​Security and retention

Events

Endpoint routing

Event envelope

Verify the signature

Delivery and retries

Security and retention