Testing webhooks

Every event below is delivered the way a real one is: signed with your endpoint's secret, carrying an idempotency key, retried on failure and recorded in your delivery log. What differs is the payload, which describes nothing that happened — the ids are placeholders and data.testMode is true.

That is the point. A mock of our side would only test our side; this tests yours.

Before you startCopy Anchor Link

You need an enabled endpoint subscribed to the event you want to send. Add one against your API connection in the Supliful dashboard, then come back. If no endpoint subscribes, the button reports that rather than failing.

Send oneCopy Anchor Link

What arrivesCopy Anchor Link

{
  "type": "order.shipmentCreated",
  "occurredAt": "2026-09-17T12:00:00.000Z",
  "data": {
    "orderId": "test_00000000-0000-4000-8000-000000000000",
    "externalOrderId": null,
    "testMode": true,
    "shipmentId": "test_shipment",
    "trackingNumber": "TEST123456789",
    "trackingUrl": "https://example.com/track/TEST123456789"
  }
}

Treat data.testMode as the signal to skip anything with consequences — charging a customer, marking an order shipped, emailing a buyer. The ids are not real, so looking them up through the API reference returns 404.

Verifying the signatureCopy Anchor Link

This is what the exercise is for. Recompute the HMAC over ${timestamp}.${rawBody} using your endpoint's secret, compare it to the v1= value in X-Supliful-Signature, and reject a timestamp older than five minutes. During a secret rotation the header carries one v1= per live secret — match any of them.

If your consumer accepts a test event but rejects a real one later, the difference is almost always that the body was re-parsed and re-serialised before hashing. Hash the bytes as they arrived.

Test ordersCopy Anchor Link

A test event is not tied to an order. To exercise the order path instead, send POST /v1/orders with testMode: true: it is validated exactly like a real order, kept for two hours, never charged and never fulfilled, and its id is prefixed test_.