Webhook Deliveries

Review delivery attempts and outcomes for each endpoint.

Delivery Statuses

• pending — accepted and awaiting delivery attempt

• retrying — previous attempt failed and will be retried

• delivered — successful delivery

• failed — no more retries will be attempted

Retry Behavior

ALPHA attempts each delivery up to 4 times (1 initial attempt plus 3 retries) using a fixed backoff schedule:

• Retry 1 — 30 seconds after the initial attempt

• Retry 2 — 2 minutes after retry 1

• Retry 3 — 10 minutes after retry 2

After the 4th attempt fails, the delivery is marked failed and no further retries are attempted.

Note

A retry does not mean duplicate business intent. It means ALPHA did not receive a confirmed success response for a prior attempt.

Idempotency Guidance

Webhook handlers must be idempotent. The same event can be delivered more than once in failure and retry scenarios.

Recommended approach:

• Store processed event id

• Skip duplicate processing when an id is already handled.

• Keep handler side effects safe for re-entry.

• If you need an order-level guard as well, use data.order_id.

HTTP Response Expectations

• 2xx — delivery is marked delivered.

• 5xx — delivery is retried until the max attempt count is reached.

• 1xx, 3xx, 4xx — delivery is marked failed immediately. No retries. A 4xx indicates a receiver-side problem that a retry will not fix; fix the receiver and then use Send test in the Portal to redeliver.

• Network errors or timeouts — delivery is retried.

Important

Your endpoint must respond within 10 seconds. Slower responses are treated as a timeout and retried.

Important

Return 2xx only after the event is durably accepted by your system (for example persisted to a queue or database).

Track delivery history and troubleshoot failures from the ALPHA Portal.