How each response is handled
Replaying a request the endpoint has already rejected as invalid is not expected to succeed, which is why other
4xx responses are not retried. Respond promptly: an attempt that gets no response in time counts as a network failure.
Backoff and the attempt limit
The wait after each failed attempt doubles, from about 30 seconds to a ceiling of one hour:
A
Retry-After header on a retryable response, in seconds or as an HTTP date, replaces the computed wait and is honoured up to the same one-hour ceiling.
Read the attempt limit from capabilities.webhooks.deliveryPolicy.maxAttempts in GET /v2/partners/config rather than assuming a number:
Delivery statuses
A retry is the same delivery. It keeps the
x-stableyard-delivery ID, the x-stableyard-event-id and the body; only x-stableyard-timestamp and the signature are new. If one endpoint succeeds while another subscribed to the same event fails, only the failing endpoint is retried.
Endpoint restrictions
Endpoints must be HTTPS with no embedded credentials. Redirects are not followed, and destinations that resolve to local, private or metadata addresses are rejected outright, solocalhost and private-network URLs cannot receive deliveries.
These rules are checked when you create the endpoint and again before every attempt.
Inspect deliveries
In the Partner Dashboard, Developers → Event stream lists one endpoint’s deliveries, newest first, with the event name, status, your endpoint’s response code, the attempt count and when the delivery was created. Open a delivery to see its delivery ID, the request body that was sent, your endpoint’s response and, while a retry is scheduled, when the next attempt runs.Requeue a delivery
Once the endpoint is fixed, requeue a failed or abandoned delivery from Developers → Event stream. The same delivery is sent again with its attempt count reset, so it gets the full attempt budget. Endpoints that already received the event are not sent it again. A requeue is refused when the endpoint is notactive, the delivery is not failed or abandoned, the endpoint is no longer subscribed to that event, or the delivery is being processed or already requeued.
Requeueing only helps if someone is watching, so alert on abandonment rather than on the first failure.
Endpoint changes and pending deliveries
Related
Webhooks overview
Endpoints, delivery guarantees and headers.
Verifying signatures
Retries are re-signed; verify each one the same way.
Event catalog
Every partner event and what it means.
Reconciliation
Sweep on your own schedule so a lost event never loses money.