Partner integration

Vendor order webhook

Send Boucher Brothers a complete order snapshot whenever an order is created, updated, or cancelled on your platform. We store the latest order for operational review and reconciliation without creating reservations or changing inventory.

HTTPSHMAC-SHA256JSONIdempotent

Endpoint

Production webhook destination

POST https://boucher.app/api/webhooks/orders
Content-Type: application/json

Authentication

Every delivery must include a unique event ID, a Unix timestamp in seconds, and a lowercase hexadecimal HMAC signature.

X-Boucher-Event-Id: evt_01JABC123
X-Boucher-Timestamp: 1787875200
X-Boucher-Signature: <64-character hex digest>

Signing input

Compute HMAC-SHA256 over <timestamp>.<exact raw JSON body> using the shared secret. Requests outside a five-minute clock window are rejected.

import { createHmac } from "node:crypto"

const timestamp = Math.floor(Date.now() / 1000).toString()
const rawBody = JSON.stringify(payload)
const signature = createHmac("sha256", webhookSecret)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex")

Supported events

order.created

New order placed

order.updated

Order details changed

order.cancelled

Order cancelled

Updates and cancellations must contain a complete current order snapshot, not only changed fields.

Payload contract

{
  "schemaVersion": "1.0",
  "eventType": "order.created",
  "eventAt": "2026-08-28T15:30:00Z",
  "order": {
    "orderNumber": "ORD-104582",
    "status": "confirmed",
    "validFrom": "2026-09-05T13:00:00-04:00",
    "validUntil": "2026-09-05T18:00:00-04:00",
    "location": { "id": "don-cesar", "name": "The Don CeSar" },
    "guest": {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "+17275550100"
    },
    "items": [
      {
        "vendorItemId": "ITEM-PASS-01",
        "sku": "GROUP-PASS",
        "name": "Group Pass",
        "quantity": 4,
        "metadata": { "guests": 4 }
      }
    ],
    "metadata": { "salesChannel": "vendor-platform" }
  }
}

Validation limits

Maximum body size: 256 KB
One to 200 items
Quantity: integer from 1 to 1,000
Valid-until must follow valid-from
Order and item IDs: 150 characters
Guest and item names: 250 characters

Responses

Code	Meaning	Retry
`200`	Processed, duplicate, or safely ignored	No
`400`	Invalid headers or payload	After correction
`401`	Invalid signature or stale timestamp	After correction
`503`	Integration not activated	After coordination
`500`	Temporary processing failure	Yes

{
  "accepted": true,
  "duplicate": false,
  "outcome": "processed"
}

Delivery and retries

Event ordering

Set eventAt to the original change time. Older out-of-order events are recorded but cannot overwrite newer state.

Idempotency

Reuse the same event ID for every retry of one logical event. A duplicate 200 response is final.

Suggested retry intervals: 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours, and 6 hours. Retry network failures and 5xx responses only.

Go-live checklist

1Securely exchange the shared HMAC secret.
2Send a signed order.created test event.
3Send an order.updated event with a new event ID.
4Retry the update using the same event ID to verify idempotency.
5Send order.cancelled and confirm final status.
6Receive written production approval from both parties.

Ready for integration testing

Contact your Boucher Brothers implementation representative to exchange credentials and coordinate the first test delivery.