What Happens if a Webhook Notification Can’t Be Delivered?

There might be times when a notification can’t be delivered to your listener endpoint (for example, if your endpoint is offline while undergoing a software upgrade). In the event of a delivery failure, Webhooks v3 automatically schedules delivery attempts based on the following timetable:

  • Webhooks v3 waits 3 seconds and then tries again.
  • If the second delivery attempt fails Webhooks v3 waits 30 seconds and then tries again.
  • If the third delivery attempt fails Webhooks v3 waits 5 minutes and then tries again.
  • If the fourth delivery attempt fails Webhooks v3 waits 1 hour and then tries again.
  • If the fifth delivery attempt fails Webhooks v3 waits 24 hours and then tries again.

If delivery can’t be made after six tries Webhooks v3 gives up and assigns the notification the failure state. After 7 days events are automatically deleted from the event store.

The retry schedule also depends on the HTTP status code returned from the listener endpoint. For example, suppose you make a first attempt at delivering a notification and the server responds with a 5xx status code. That’s fine: a 5xx error typically refers to a short-lived problem (for example, temporary network congestion). Because the problem is likely to be resolved soon, the event state is changed to awaiting-retry and, after a few seconds, delivery will be attempted again.

However, suppose your first attempt to deliver a notification fails with a 3xx error. A 3xx error means that an additional action, such as a redirection, must be completed before the request can be accepted and processed. A webhooks delivery should never require an additional action, and should never be redirected to another server. Consequently, any time a 3xx error is returned the event state is immediately set to failure, and no retries are scheduled.

The following table features a more complete list of the actions taken following a specific event delivery response:

Response

Next state

Notes

Malformed endpoint URL

failure

If the endpoint URL is invalid there’s no point trying to deliver an event: where would you even deliver that event to? If this error occurs the customer will have to use the subscription API to assign a new (and valid) endpoint URL.

Note that this error is unlikely to occur simply because URLs are validated any time a subscription is created or updated.

DNS error

failure

Usually the result of a DNS configuration error that has made the endpoint unreachable. If this error is returned you should ping the endpoint URL and see if you get a response. If not, you will need to make a change to your DNS configuration.

SSL error

failure

Usually a result of the customer having an expired, incorrectly-configured, or otherwise-invalid SSL certificate. Webhook events cannot be delivered unless the customer has a valid and accessible certificate from a public Certificate Authority.  

Network error

awaiting-retry

Error accompanied by messages such as “Connection refused,” or “Connection closed.” Because these types of network issues (e.g., network congestion) are generally sporadic and short-lived, the event will be marked as awaiting-retry and another delivery attempt will be made based on the retry schedule.

Endpoint responds with HTTP 1xx

failure

The server has accepted the request, and processing is continuing. This is considered a failed request because processing a webhook request should only take a fraction of a second.

If an HTTP status code of 1xx is returned the event state is changed to failure and no further attempts are made to deliver the notification.

Endpoint responds with HTTP 2xx

success

The notification was successfully delivered.

Endpoint responds with HTTP 3xx

failure

Further action (often a redirect of some kind) is required before the request can be acted upon.

If an HTTP status code of 3xx is returned then the event state is changed to failure and no further attempts are made to deliver the notification.

Endpoint responds with HTTP 4xx

awaiting-retry

The server rejected delivery due to a problem with the request itself (for example, a parameter name might have been misspelled).

If a 4xx error is returned the event will be marked as awaiting-retry and another delivery attempt will be made based on the retry schedule.

Endpoint responds with HTTP 5xx

awaiting-retry

The initial request was accepted but a server error prevented delivery from being completed; 5xx errors are often the result of transient network congestion or server overload.

If a 5xx error is returned the event will be marked as awaiting-retry and another delivery attempt will be made based on the retry schedule.

Request timeout

awaiting-retry

The server failed to respond to the webhooks request within 10 seconds. In this case, the event will be marked as awaiting-retry and another delivery attempt will be made based on the retry schedule.

Retry limit reached

failure

Webhooks v3 has made 6 unsuccessful delivery attempts. As a result the event state is changed to failure, and no further delivery attempts will be made.