Webhook retries
Understand webhook delivery attempts and build a receiver that safely handles repeat notifications.
A webhook delivery record tracks whether an event was delivered successfully and records information about attempted delivery. Your application must be safe when the same business event is delivered more than once.
Delivery information
Webhook delivery records can include:
| Field | Meaning |
|---|---|
event | The webhook event type. |
timestamp | When the webhook record was created. |
attemptNumber | The number of delivery attempts made. |
lastStatusCode | The HTTP status returned by the most recent attempt. |
lastAttemptAt | When the most recent attempt occurred. |
nextRetryAt | When a subsequent retry is scheduled, when applicable. |
responseTime | Response time recorded for the delivery. |
errorMessage | Error information for a failed delivery, when available. |
succeeded | Whether delivery completed successfully. |
Make event handling idempotent
Retrying delivery is normal network behavior. Build your receiver so that processing a repeated event does not charge twice, create duplicate records, or send duplicate customer notifications.
A practical pattern is to store a durable event or business-operation key before applying side effects. If the same key is received again, return success without repeating the operation.
Respond deliberately
- Return a successful response only after you have accepted the event for safe processing.
- Return an error when your application cannot accept the event and needs delivery to be retried.
- Move slow work to a queue or background worker so your HTTP receiver can respond promptly.
- Monitor unsuccessful deliveries and investigate recurring errors using the event type, attempted time, and safe request context.
Do not infer a retry schedule from this page. Confirm retry timing and any account-specific behavior with the webhook configuration or support channel provided for your service.