Notification retry
Notifications are delivered using an at-least-once delivery model.
This means the system attempts to deliver every notification and will retry delivery automatically if the receiving system does not acknowledge the request successfully.
Retries ensure that temporary network problems or short outages in the receiving system do not cause events to be lost.
When retries happen
A notification delivery is considered unsuccessful when:
- the receiving system does not respond
- the request fails due to a network error
- the receiving system returns a non-success HTTP status code
In these situations the system schedules another delivery attempt.
Retries continue until the notification is successfully accepted by the receiving system.
Backoff and limits
Retry attempts are automatically scheduled after a failure.
Each retry attempt sends the same payload as the original notification.
Because notifications follow an at-least-once delivery model, a receiving system may receive the same notification more than once.
The retry mechanism is designed to maximize the chance that notifications are eventually delivered even when external systems are temporarily unavailable.
Failure handling
If a delivery repeatedly fails, each attempt is recorded in the notification log.
This allows integrators to inspect:
- the original delivery attempt
- subsequent retry attempts
- the response returned by the receiving system
These records make it possible to diagnose network problems, authentication failures, or endpoint misconfiguration.
Receiver guidance
Because notifications may be retried, receiving systems must be able to safely handle duplicate messages.
A common approach is to treat the combination of:
hook_id- row identifiers in the payload
as an idempotency key.
If a message with the same identifiers has already been processed, the receiving system should ignore the duplicate notification.
Related resources
Related concepts