Webhook retries

Before replaying a webhook

Use this page when an inbound or outbound webhook stops after retries, fails signature validation, times out at the receiver or conflicts with idempotency. Start from the attempt because it owns retry timing, payload hash, signing state, receiver response and dedupe.

• Check the retry schedule
• Review `retry_after`, `webhook_status`, `idempotency_key`, `signature_header` and receiver state before replay.
• Keep payloads immutable; fix endpoint, signing or idempotency state instead of editing event data.

Triage the webhook attempt

Follow the path `Webhook attempt → Retry schedule → Signature and receiver check → Replay, rotate or stop`.

1. Open the webhook attempt from `/settings` or the owning delivery surface. Result: `webhook_attempt_id`, `event_type`, `webhook_status`, `retry_count` and `max_retry_count` are visible before replay.
2. Read `retry_after`, `last_attempt_at`, `next_retry_at`, `receiver_status_code`, `receiver_timeout_ms` and `idempotency_key`. Result: the customer knows whether to wait, fix the receiver or stop.
3. Verify `signature_header`, `signing_secret_status` and `payload_hash` against the receiver. Result: the payload can be validated without editing event content.
4. If `WEBHOOK_SIGNATURE_INVALID` appears, rotate or reconfigure the secret through `/settings`. Result: the receiver validates the original payload instead of disabling signature checks.
5. If `WEBHOOK_RECEIVER_TIMEOUT` or `WEBHOOK_ENDPOINT_UNREACHABLE` appears, fix endpoint availability before replay. Result: WebRiskOps does not burn retries against an unreachable receiver.
6. If `WEBHOOK_IDEMPOTENCY_CONFLICT` appears, keep the same `idempotency_key` for the same event and inspect downstream dedupe. Result: duplicate processing is avoided.
7. If `WEBHOOK_RETRY_EXHAUSTED` appears, review `retry_count`, `max_retry_count` and `retry_after` before replay. Result: exhausted events are replayed only after the root cause is clear.
8. Retry ticket export webhook delivery from `/reports/{report}/ticket-exports` only when provider or receiver state is ready. Result: outbound evidence delivery remains tied to the export attempt.
9. Stop when payload data is unauthorized, endpoint ownership is unclear, signing cannot be validated or receiver policy rejects the event. Result: unsafe payload delivery stays blocked.
10. Continue to Ticket export webhooks, Webhook export, Ticket export failures or Provider connection errors based on the owner that remains. Result: the next guide owns endpoint setup, export delivery or provider recovery.

Webhook retry reasons

Use the reason code to decide whether to wait, replay, rotate or stop.

• `WEBHOOK_RETRY_EXHAUSTED` means automatic delivery stopped after the configured retry window.
• `WEBHOOK_SIGNATURE_INVALID` and `WEBHOOK_SECRET_ROTATION_REQUIRED` mean the receiver cannot validate the payload with the current signing setup.
• `WEBHOOK_RECEIVER_TIMEOUT` and `WEBHOOK_ENDPOINT_UNREACHABLE` mean the endpoint must become reachable before replay.
• `WEBHOOK_IDEMPOTENCY_CONFLICT` means the receiver already processed or rejected the same logical event key.
• `WEBHOOK_PAYLOAD_REJECTED` means receiver policy, schema validation or destination ownership rejected the event.

Replay rotate or stop rules

Fix the owner of the failure before replay.

• Wait until `retry_after` or `next_retry_at` before replaying an exhausted or rate-limited event.
• Keep `payload_hash` and `idempotency_key` stable for the same event.
• Rotate secrets only through `/settings` and verify the receiver reads the documented `signature_header`.
• Stop when endpoint ownership, payload authorization, signing validation or receiver policy is not safe.

Ready and blocked webhook states

A webhook is ready when endpoint, signing and idempotency state can accept the original event.

• Ready: endpoint returns an intentional 2xx after processing, signature validation passes, idempotency accepts the event, retry cooldown has passed and the owning workflow still needs delivery.
• Still blocked: exhausted retries, invalid signature, unreachable receiver, receiver timeout, idempotency conflict, rejected payload, unclear endpoint ownership or unsafe payload data.
• Stop: the receiver cannot validate signatures safely, the payload includes unauthorized data or the endpoint belongs to another customer/system.

Continue after webhook triage

Use the linked guide for the workflow that still owns the block.

• Ticket export webhooks explains outbound ticket-export event payloads, signing and delivery expectations.
• Webhook export explains ticket-export webhook targets and fallback behavior.
• Errors, idempotency, retries and rate limits explains API retry semantics and idempotency keys.
• Ticket export failures explains outbound export attempts after provider or webhook delivery fails.
• Provider connection errors explains auth, base URL, permission and rate-limit recovery when a provider owns the block.