Webhooks overview

Everything else in these docs is a request you send us. Webhooks are the other direction: when something happens to an order or to a product you hold a copy of, Supliful posts a small JSON body to a URL you register against your API connection.

Each event type has its own page — see the sidebar — and they all share the envelope below. Testing webhooks fires a real one at your endpoint before you have an order to test with.

{
  "type": "order.shipmentCreated",
  "occurredAt": "2026-09-17T12:00:00.000Z",
  "data": { "orderId": "…", "externalOrderId": "your-order-1042" }
}

Setting up an endpointCopy Anchor Link

Add the URL in the Supliful app, on the connection's page, and choose which event types it should receive. The URL must be https:// and publicly resolvable — an address inside a private network is refused, at save time and again at delivery.

Each endpoint gets its own signing secret. Two connections of the same account never share one.

Verifying a deliveryCopy Anchor Link

Every request carries X-Supliful-Signature, an HMAC-SHA256 of ${timestamp}.${body} in the form t=<unix>,v1=<hex>. Recompute it with your endpoint's secret over the bytes as they arrived — re-serialising the parsed JSON changes them — and reject a timestamp more than five minutes old.

While a secret is being rotated the header carries one v1= per live secret, so match any of them. The retired secret keeps working for 24 hours, which is your window to redeploy.

What to expectCopy Anchor Link

• Payloads are thin. They carry ids, not state. Refetch the order or product through the API when you need the detail.
• Deliveries are not ordered. A retry means a later event can arrive first, so order by occurredAt rather than by arrival.
• Retries repeat the same body. X-Supliful-Idempotency-Key is stable across every attempt of one delivery — deduplicate on it.
• Any 2xx acknowledges. We retry 5xx, 408, 429 and connection failures for about three days, waiting longer each time — from a minute up to a day; any other 4xx is treated as permanent.
• A dead endpoint is switched off. An endpoint that has not accepted a single delivery for three days is disabled, and you re-enable it in the app once the URL works again.

Every attempt is recorded in the delivery log on the connection's page, with the response code we got back and a button to send one again. The log keeps 30 days; anything older can no longer be resent.