Webhooks

Returns all webhooks registered for your account, oldest first. Signing secrets are never returned here, they are shown only once in the response of the create endpoint.

Registers an HTTPS URL of your system. Whenever the status of one of your shipments changes, we POST a JSON event to it shortly after we process the tracking data of the carrier, so you do not have to poll the tracking endpoint.

Events. The only event so far is shipment.status_changed. It fires when the aggregated Zaslat status of a shipment changes (for example INTRANSIT → ONDELIVERY → DELIVERED), not for every tracking row the carrier reports. The payload is described in the callback below and uses the same status dictionary as the tracking endpoint. It carries only identifiers and the new status; fetch the shipment detail through the API when you need more.

Signature. Every request carries the X-Zaslat-Signature header with the value sha256=<hex>, where <hex> is the HMAC-SHA256 of the raw request body computed with the webhook secret. Recompute it on your side from the exact bytes you received and compare with a constant-time comparison; reject the request when it does not match. We never send your API key to the webhook URL. The X-Zaslat-Event and X-Zaslat-Event-Id headers duplicate the event and eventId fields of the body for routing.

Delivery and retries. Your endpoint must answer with a 2xx status within 10 seconds. A 5xx response, 408, 429, a timeout or a connection error is retried with an increasing delay: 1, 5, 15 and 30 minutes, then 1, 2, 4, 8, 12 and 24 hours after the previous attempt (10 retries in total), always with the same eventId, so deduplicate by eventId on your side. Any other 4xx response is treated as a permanent rejection of that event and is not retried. A redirect is never followed and counts as a failure.

Automatic pause. When every delivery attempt has been failing for 24 hours in a row, we set active to false, record the time in disabledAt and send an e-mail to the account notification address. Events that occur while a webhook is paused are not sent and are not replayed later. Fix the endpoint and re-enable the webhook with the update endpoint (active: true), which also resets failureCount. The deliveries endpoint shows the recent attempts with status codes and errors.

URL rules. Only https:// URLs without credentials are accepted and the host must resolve to a public IP address. Private, loopback and link-local addresses (for example 10.x, 192.168.x, 127.0.0.1, 169.254.x) are refused with 400.

Limits. At most 10 webhooks per account. The same URL can be registered only once per event (409).

Secret. You can supply your own signing secret (16 to 128 characters). When you omit it, we generate a random one and return it in the secret field of this response only. It cannot be retrieved later; to rotate it, delete the webhook and create it again.

Returns a single webhook of your account. The signing secret is not included.

Changes the URL and/or the active flag of a webhook. Send only the fields you want to change; a body without any field is refused with 400. A paused webhook (active: false) keeps its configuration but receives no events until it is resumed; events from the paused period are not replayed. Setting active: true also resets failureCount and disabledAt, use it to re-enable a webhook we paused automatically. The new URL must follow the same rules as on create.

Returns the last 50 delivery attempts of the webhook, newest first: event, attempt number, HTTP status your endpoint returned, whether it succeeded and the error description. Use it to debug your endpoint. Attempts older than 30 days are removed.

Immediately POSTs one shipment.status_changed event with made-up shipment data and "test": true to the webhook URL, signed exactly like a real event, and returns what your endpoint answered. Use it to verify your signature check and parsing before real shipments start flowing. The test is sent even when the webhook is paused and it never changes the health counters or triggers the automatic pause; the attempt is recorded in the deliveries endpoint with "test": true. A failed test is still a 200 response here, look at delivered, statusCode and error.

Rate limit. At most 10 test events per 60 seconds per account; the state is returned in the X-Rate-Limit-Limit, X-Rate-Limit-Remaining and X-Rate-Limit-Reset headers, exceeding it returns 429.

Removes the webhook permanently. Events that are already queued for delivery to it are dropped. Use the update endpoint with active: false when you only want to pause it.