Skip to main content

Failure recovery

Reasons for event delivery failure could vary from an internal failure on our part to the target endpoint experiencing downtime for various reasons like server maintenance.

To help mitigate some of these failures we have a delivery retry policy and events history endpoint in place. However, note that we don't guarantee the delivery and these should not be relied upon as a fail-safe mechanism.

Retry policy

A non 2xx response is treated as an event delivery failure and the event is scheduled for redelivery. An exponential backoff retry policy with a power of 3 is used, up to 12 attempts so the 12th attempt will be done approximately 9 days after the first one.

A webhook receiver can opt out of the retry mechanism by responding to the request with a 410 (Gone) or 501 (NotImplemented) HTTP status code.

Events history

The get events endpoint can be used to get all the events that have happened for the account in the past 30 days. The response will contain all the events, even ones that you are not subscribed to. This endpoint can be useful for recovery cases where the webhook endpoint was down for a longer period of time so all delivery retries have failed.

For example, if your webhook endpoint was down between 2022-01-25T13:06:34+00:00 and 2022-01-25T17:10:57+00:00 and you want to retrieve all the missed invoice events in that period, you can fetch those specific events using filtering by creation time and event types like this:

curl -X 'GET' \
'https://<ENVIRONMENT>/v1/events?$filter=eventType%20eq%20%27invoice.created%27%20or%20eventType%20eq%20%27invoice.updated%27%20and%20created%20lt%202022-01-25T13%3A06%3A34%2B00%3A00%20and%20created%20gt%202022-01-25T17%3A10%3A57%2B00%3A00' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <API_KEY>'

The response is paginated and will look something like this:

{
"items": [
{
"id": "c1f0b219-4499-4f30-ad47-d35f8aaaa2af",
"eventType": "invoice.created",
"webhookVersion": "v1",
"data": {
"entityId": "be290e83-f087-470a-99db-88419b17c332"
},
"created": "2022-01-25T14:06:01.365+00:00",
"deliverySuccess": false
},
{
"id": "b8a21c07-7455-4a44-8b9a-e7f69e71393e",
"eventType": "invoice.updated",
"webhookVersion": "v1",
"data": {
"entityId": "be290e83-f087-470a-99db-88419b17c332",
"changes": ["state"]
},
"created": "2022-01-25T14:06:34.955+00:00",
"deliverySuccess": false
}
],
"count": 2
}

where count represents the total number of events that satisfy the provided filter. You can control the pagination by moving filter values for created field or using $top and $skip query params. For all available endpoint params check api ref.