Set your webhook endpoint
Registers, or replaces, the single webhook endpoint of your organisation. Calling it again replaces the URL, secret and event types; the new secret takes effect immediately with no overlap, so deploy it to your endpoint first.
Verification challenge. Before saving, Shipping Engine sends your URL an unsigned
POST with {"challenge":"<uuid>"} (10-second timeout). Reply with any 2xx and the body
{"challenge":"<uuid>"} or the raw uuid.
- Challenge passed: the endpoint is saved as
verifiedand starts receiving events. - Challenge failed on a new endpoint: it is saved with
verificationStatus: failed(still201) and receives no events. Fix your endpoint and call this again. - Challenge failed while you already have a verified endpoint:
422, and the current endpoint stays active and unchanged.
Always check data.challenge.success in the response.
Requires the MANAGE_WEBHOOKS permission.
bearerAuthAuthorizationBearer <token>An access token from the OAuth2 client-credentials grant. Exchange your API key
(client_id + client_secret) at the token endpoint and send
Authorization: Bearer <access_token>.
application/json- body
name*stringA label for your endpoint.
length <= 100url*stringPublic HTTPS URL with a valid certificate. Private and internal addresses are refused.
^https://urisecret*stringA random secret you generate (at least 32 characters). Used to sign every delivery. It is never returned.
32 <= lengthkeyId?stringName for this secret, sent in x-webhook-signature as keyId=. Default whsec_ + 32 hex characters.
length <= 64eventTypes?array<string>Events to receive: exact names (shipment.delivered), wildcards (shipment.*, *.delivered) or *.
1 <= items <= 20[ "shipment.*"]timeoutMs?integerHow long to wait for your 2xx, in milliseconds.
1000 <= value <= 6000010000maxAttempts?integerDelivery attempts per event, including the first.
1 <= value <= 508The endpoint is saved. It receives events only if challenge.success is true
(verificationStatus: verified).
application/json- response
statusCode*integermessage*stringdata*curl -X POST 'https://sandbox-api.fastrac.example/b2b/webhook/setWebhook' \ -H 'Content-Type: application/json' \ -d '{ "name": "Production events", "url": "https://hooks.sinartebet.co.id/shipping-engine", "secret": "9f2c7a1e4b8d3f6a0c5e2b7d9a1f4c8e", "keyId": "whsec_main_2026"}'{ "statusCode": 201, "message": "Webhook endpoint registered", "data": { "id": 41, "name": "Production events", "url": "https://hooks.sinartebet.co.id/shipping-engine", "isEnabled": true, "verificationStatus": "verified", "apiVersion": "V3", "timeoutMs": 10000, "maxAttempts": 8, "eventTypes": [ "shipment.*" ], "activeSecretKeyIds": [ "whsec_main_2026" ], "createdAt": "2026-11-20T03:00:00.000Z", "updatedAt": "2026-11-20T03:00:00.000Z", "backoffUntil": null, "challenge": { "success": true, "statusCode": 200 } }}Was this page helpful?
Retrieve your webhook endpoint GET
Returns your organisation's webhook endpoint, as a list with zero or one item. Check `verificationStatus`: events are delivered only while it is `verified` and `isEnabled` is `true`. `failureCount` and `backoffUntil` show whether deliveries are currently failing. Requires the `READ_WEBHOOKS` permission.
shipment.dispatched Webhook
The courier accepted the booking and assigned an airway bill. For API orders this arrives right after **Create an order** returns. This event has its own **flat** body, unlike the other shipment events: `shipment_id` and `order_id` are numeric IDs, and `status` is `PENDING_PICKUP` or `PENDING_DROPOFF`.