Webhook retries and errors

A webhook crosses two systems. Assume that retries, duplicate deliveries, temporary outages, and late responses can occur.

Expected responses

Receiver response	Recommended outcome
`2xx`	Event accepted. Bold can mark the delivery as successful.
`4xx`	Consumer error or rejected data. Review the configuration and contract.
`5xx`	Temporary receiver error. The event should be retryable.
Timeout	The receiver did not respond in time. Queue the work and respond promptly.

Do not return 2xx if you discarded the event without saving it. Bold will assume that delivery succeeded.

Bold attempts to send a notification up to five times. After each failure, it schedules the next attempt with an exponential delay.

Setting	Behavior
Maximum sending time	30 seconds.
Maximum attempts	5 automatic attempts.
Automatic delay	`10 * 2^n` seconds, where `n` is the number of attempts made.
Final status after exhausting attempts	`Failure`.
Manual retry	Only for notifications in `Failure`, through `POST /v1/notifications/webhook/{id}/retry`.

Each attempt stores the HTTP code, response body, or error message. Query GET /v1/notifications/webhook/{id}/attempts to diagnose it.

Failed attempt	Approximate next attempt
1	20 seconds later.
2	40 seconds later.
3	80 seconds later.
4	160 seconds later.
5	No further automatic attempt.

When you request a manual retry, the notification returns to Pending and is scheduled for immediate delivery.

Validate the data received

Check that eventName, majorVersion, minorVersion, and the entity identifier are as expected.

Detect duplicates

If you already processed the event, return 2xx without repeating external effects.

Queue the work

Save the event in your system and respond promptly.

Process in the background

Call management systems, analytics tools, or other services outside the HTTP response period.

if already_processed(event.eventId):
  return 200

store(event)
enqueue(event.eventId)
return 202

If your integration becomes out of sync, use the paginated API to reconcile its state, then resume normal webhook processing.