Skip to Content
FastracDocs
API reference

Set your webhook endpoint

POST
/b2b/webhook/setWebhook

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 verified and starts receiving events.
  • Challenge failed on a new endpoint: it is saved with verificationStatus: failed (still 201) 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.

Authorization

bearerAuth
headerAuthorizationBearer <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>.

Request Body

application/json
  1. body
name*string

A label for your endpoint.

Lengthlength <= 100
url*string

Public HTTPS URL with a valid certificate. Private and internal addresses are refused.

Match^https://
Formaturi
secret*string

A random secret you generate (at least 32 characters). Used to sign every delivery. It is never returned.

Length32 <= length
keyId?string

Name for this secret, sent in x-webhook-signature as keyId=. Default whsec_ + 32 hex characters.

Lengthlength <= 64
eventTypes?array<string>

Events to receive: exact names (shipment.delivered), wildcards (shipment.*, *.delivered) or *.

Items1 <= items <= 20
Default
[  "shipment.*"]
timeoutMs?integer

How long to wait for your 2xx, in milliseconds.

Range1000 <= value <= 60000
Default10000
maxAttempts?integer

Delivery attempts per event, including the first.

Range1 <= value <= 50
Default8

Response Body

The endpoint is saved. It receives events only if challenge.success is true (verificationStatus: verified).

application/json
  1. response
statusCode*integer
message*string
data*
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"}'
Example Response
{  "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?