Webhooks

Bigblue sends inventory and order status changes to your HTTPS endpoint, signed with HMAC-SHA256.

With webhooks, Bigblue sends you changes as they happen, so you don't need to poll ListInventories or ListOrders. Webhooks don't count against your rate limit.

Event types

INVENTORY_UPDATE

Stock changed for one or more products. Up to 100 rows per request.

ORDER_STATUS_UPDATE

An order's status changed. One order per request.

A third type, URL_VERIFICATION, is only sent when you register an endpoint. See Verify your endpoint.

Setting up a webhook

You create webhooks in the Bigblue app. The Store API has no endpoint for it.

In the Bigblue app, copy your account's webhook shared secret. Bigblue signs every webhook request with it, including the verification request sent when you register. Your endpoint needs it before you register.

Deploy your endpoint

The URL must use HTTPS and must answer the verification challenge.

Register it in the app

Add the webhook in the Bigblue app with your URL and an event type. Bigblue sends a URL_VERIFICATION request right away. If your endpoint doesn't return the challenge, the webhook isn't saved.

Verify every request

Check the signature on each request before you use the data. See Verify signatures.

Respond quickly

Bigblue waits 20 seconds and retries any response that isn't 2xx. Return 200 first, then process the event. See Delivery and retries.

You can register several endpoints for the same event type. Each one receives every event.

Request format

POST /webhooks/bigblue HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
User-Agent: Bigblue-Webhook-Engine
X-Bigblue-Event-Type: ORDER_STATUS_UPDATE
X-Bigblue-Hmac-SHA256: 5rBqz1S0K8p3xW7fT2vN9cH4mJ6dL0aY8bE1uQ3sR5k=

{ "update_time": "2026-03-17T09:12:04Z", "order_status": { ... } }

X-Bigblue-Event-Typestring

INVENTORY_UPDATE, ORDER_STATUS_UPDATE or URL_VERIFICATION. The body depends on this value.

X-Bigblue-Hmac-SHA256string

Base64 HMAC-SHA256 of the raw body, signed with your shared secret.

User-Agentstring

Always Bigblue-Webhook-Engine. Don't use it to check where a request comes from.

Content-Typestring

Always application/json.

Both event bodies include update_time in RFC 3339 UTC.

Events without webhooks

Only inventory and order status changes have webhooks. For other changes, poll the API:

To know when	Do this
An inbound shipment is received	Poll `GetInboundShipment`. An inventory webhook is also sent when stock arrives.
A parcel has new carrier events	Poll `ListTrackings` for shipped orders.
A return is received	An inventory webhook is sent. Get the details with `GetReturn`.
A ticket needs your reply	Poll `ListOrderTickets`.

Missed events

Bigblue retries a failed request for up to 60 hours, then stops. Events missed during a longer outage are lost. Run a nightly sync with ListInventories and ListOrders to catch them.