FulfillbotDocs
Menu
MarkdownDownload

Webhooks

Webhooks tell your system when something changes, so you don't have to poll. When an event you subscribed to happens, we send an HTTPS POST to your endpoint with a small JSON body: the event type, the id of what changed and its new status. Fetch the details with the API.

Set up an endpoint

  1. In the portal, open Settings → API access and go to Add a webhook endpoint.
  2. Enter the endpoint URL: a public https:// address of up to 2,000 characters, without a user name, password or # part. localhost, single-word host names, private and local IP addresses, and names ending in .local, .internal, .lan, .localhost or .home.arpa are refused.
  3. Optionally add a description of up to 100 characters.
  4. Tick the events you want: see Webhook events.
  5. Click Add endpoint, then copy the signing secret (whsec_...) straight away. It is shown only once. Store it like a password.

You must have signed in within the last 10 minutes to add an endpoint or create a new secret. An account can have up to 5 endpoints, including turned-off ones. Webhooks need API access to be on for your account.

Manage endpoints

Open an endpoint in Settings → API access to:

  • change its URL, description and events (Save changes);
  • Create a new secret: it replaces the old secret at once, with no overlap, so update your receiver straight after;
  • Send test event: see Webhook delivery and retries;
  • Turn off and Turn on;
  • Delete endpoint;
  • see Recent deliveries: the last 50 deliveries with their status, attempts and your endpoint's answer.

While your account is on hold you can't add or change endpoints or turn them on. You can still turn them off, delete them, create a new secret and send test events.

What a webhook looks like

POST /your/webhook/path HTTP/1.1
Content-Type: application/json
User-Agent: Fulfillbot-Webhooks/1.0
X-Webhook-Id: evt_3f9a1c2b7d4e5f60718293a4
X-Webhook-Event: order.status_changed
X-Webhook-Attempt: 1
X-Webhook-Signature: t=1762653600,v1=78e8462fdd961bd012879276064959675d3a21748eb85da05b69fb9f18e51c0d

{"id":"evt_3f9a1c2b7d4e5f60718293a4","type":"order.status_changed","createdAt":"2026-11-09T02:00:00.000Z","data":{"id":"cm3o7rd0e0001h2j3k4l5m6n","status":"SHIPPED"}}

This example is signed with the example secret whsec_example_only_do_not_use. Its timestamp is in the past, so to try your verification code with it, pass the example's time (1762653600) as the current time: the samples on Verifying webhook signatures take an optional now argument for this. Never do that in production.

The table below describes the body of this example. type and data differ per event: see Webhook events.

Field Type Description
id string Event id. Retries and every endpoint get the same id; use it to skip duplicates.
type string The event type. Always order.status_changed.
createdAt string (date-time) When the change happened (ISO 8601, UTC).
data object What changed: the id of the resource and its status after the change. For webhook.test, id is the endpoint id and status is TEST.
data.id string Order id. Fetch it with GET /v1/orders/{id}.
data.status string The status after the change (uppercase code). One of NEEDS_ATTENTION, READY, BACKORDERED, RESERVED, WEIGHED, SHIPPED, CANCELLED.

Payloads never contain personal data, amounts, images or file links. Fetch the resource with its GET endpoint for the details.

Headers

Header Value
Content-Type application/json
User-Agent Fulfillbot-Webhooks/1.0
X-Webhook-Id The event id. The same on every retry and for every endpoint that gets the event; use it to skip duplicates.
X-Webhook-Event The event type, for example order.status_changed.
X-Webhook-Attempt Which attempt this is, 1 to 6.
X-Webhook-Signature t=<unix seconds>,v1=<hex HMAC-SHA256>. See Verifying webhook signatures.

Next