Webhook retries, failures and automatic suspension

Purpose#

This reference explains what happens when your system does not answer a webhook message: when it is retried, when the link is suspended automatically, and how to use the message log and resend.

What counts as success or failure#

• Success: an HTTP 2xx answer within 10 seconds.
• Failure: any other answer, including 3xx (redirects are not followed, and the error text says to enter the final URL), a timeout, DNS, connection or TLS errors, and a URL that no longer passes the public-address check at send time. The error text is saved.
• The first attempt is made when the event happens (after the request that caused it has been answered); later ones are handled by a scheduled job.

Retry schedule#

• That is 8 attempts in total. After the eighth the message is Failed and is not retried automatically (use "Resend").
• The times are minimums: the scheduled job (webhooks:retry) runs every minute and handles up to 100 due messages per run, so each attempt can be about a minute late.
• Every attempt carries the same body, X-DS-Event-Id and X-DS-Delivery; X-DS-Attempt, X-DS-Timestamp and X-DS-Signature change.
• Test messages (ping) are not retried automatically.
• Order is not guaranteed and a message can repeat; ignore duplicates using X-DS-Event-Id.

Automatic suspension#

• Each link has a counter of consecutive failures: every failed attempt (for any message, including a test) adds 1, and any successful attempt resets it to 0.
• At 40 the link becomes inactive ("Suspended") and a reason is saved, such as "Stopped automatically after 40 consecutive failed attempts — last error: ...". The reason is shown in red under the link in the panel, and returned as disabled_reason by GET /api/v1/webhooks.
• The counter counts attempts, not messages; one message that fails all eight attempts adds 8.
• A suspended link receives no new events, and they are not stored for it. Messages waiting for a retry are marked Failed ("Link disabled or deleted") when their turn comes, without being sent, if the link is still suspended; if you re-enable the link before then, they are sent normally. Deleting a link in the panel marks its pending messages Failed immediately ("Link deleted"). Deleting it through DELETE /api/v1/webhooks/{id} does not touch them: they are marked Failed ("Link disabled or deleted"), without being sent, when their retry time comes.

Message log#

It sits at the bottom of the "Outgoing Webhook" page under "Message log — Last 30 days" (panel only):

• Columns: "Time", "Event", "Link", "Status" (Succeeded, Awaiting retry, Failed, with the next attempt time), "Response" (HTTP status and duration in ms) and "Attempts".
• The eye icon opens a window with "What we sent" (the body), "Your system response" (HTTP status and the first 2000 characters of the answer), the event id, attempts, URL and error.
• Filters: link, event, status, and a search by tracking number, evt_ id or UUID. 25 messages per page.
• The log keeps only the last attempt's data for each message. Rows older than 30 days are deleted by an hourly cleanup.
• Resend: a button on every row while the link is enabled. It sends immediately, even if the message had succeeded, and counts as one more attempt (X-DS-Attempt increases). If a failed resend is attempt 7 or lower, the next attempt follows the table; from attempt 8 on the message stays Failed.

Recovering after an outage#

1. Fix the endpoint

   Make it answer 2xx. Find the cause in the "Response" column and in the message details window.

2. Re-enable a suspended link

   Click "Edit", tick "Enabled" and click "Save"; the counter is reset and the suspension reason is cleared. Merchants can also do this through the API: PATCH /api/v1/webhooks/{id} with {"active": true}; company admins use the panel (the company API has no webhook endpoints).

3. Try it with "Send test"

   The button appears while the link is enabled. A successful test resets the counter and confirms that your system verifies the signature and answers.

4. Resend the failed messages

   In the "Message log" choose the status "Failed" and click "Resend" on each message you need. Messages still waiting for a retry are sent when their turn comes.

5. Make up for missed events

   Because events are not stored while a link is suspended, read the state of your parcels: merchants with GET /api/v1/parcels or GET /api/v1/parcels/{tracking}; company admins with GET /api/company/v1/parcels (filter with updated_since) or GET /api/company/v1/parcels/{tracking}.

Common mistakes#

• A URL that redirects (such as https://example.com to https://www.example.com, or a path that sends you to a login page): a 3xx counts as a failure. Register the final URL.
• Processing for more than 10 seconds before answering: answer 2xx at once and process in the background.
• Answering 4xx for events you do not care about: it counts as a failure, so it is retried and then the link is suspended. Return 2xx and ignore the event.
• Answering 401 after renewing the signing key: update the key on your side, because every message you reject counts as a failure.

Permissions and limits#

• Same access as in the webhooks article: a merchant from the merchant panel, a company admin from "Integrations and API".
• "Resend" is limited to 30 per minute and "Send test" to 10 per minute.