Webhook Delivery Retry & Dead-Letter Alerting

Available from: v1.0.262

The platform now automatically retries failed webhook deliveries and alerts your organisation when deliveries cannot be recovered. This removes the need for manual intervention in most failure scenarios and ensures you are notified promptly when a webhook reaches a terminal failure state.

How It Works

Two scheduled processes work together to provide end-to-end delivery reliability.

1. Retry Worker (every 15 minutes)

A scheduled job runs every 15 minutes (*/15 * * * *) and processes all pending webhook deliveries that are due for a retry.

Selection criteria:

webhook_deliveries.status = 'pending'
webhook_deliveries.nextRetryAt <= now

Processing logic:

Outcome	Resulting Status	Action
Re-delivery succeeds	`delivered`	Record updated, no further action
Re-delivery fails, attempt < 5	`pending`	`nextRetryAt` rescheduled for next window
Re-delivery fails, attempt = 5	`failed`	Admin notification sent immediately

The retry counter is tracked per webhook_deliveries record. Once a delivery reaches failed it is no longer eligible for automatic retry.

2. Daily Dead-Letter Summary

Once per day the system counts all failed deliveries grouped by organisation.

Organisations with failed deliveries receive a summary notification delivered to all org owners.
Organisations without failed deliveries are skipped entirely — no spurious alerts.

Delivery Statuses

Status	Meaning
`pending`	Delivery has not yet succeeded; awaiting next retry window
`delivered`	Delivery was accepted by the target endpoint
`failed`	Maximum retry attempts (5) exhausted; requires manual review

Notifications

Two types of notifications are generated by this workflow:

Immediate admin alert — fired when a single delivery transitions to failed after exhausting all 5 retry attempts.
Daily org-owner summary — fired once per day per organisation that has at least one failed delivery. Includes a count of failed deliveries so owners can triage outstanding issues.

Affected Data Entities

webhook_deliveries — primary entity; status and nextRetryAt fields are read and updated by the retry worker.
webhooks — referenced to resolve endpoint URLs and configuration for re-delivery.
organizations — used to group failed deliveries and identify org owners for the daily summary.
notifications — records created when a delivery fails terminally or when the daily summary is dispatched.

Operational Notes

The retry window is controlled by the nextRetryAt field on each webhook_deliveries record. Adjusting this field directly will influence when the next retry is attempted.
There is no automatic reactivation of failed deliveries. To re-queue a failed delivery, update its status back to pending and set a new nextRetryAt value.
Admin notifications and daily summaries are both routed through the standard notifications entity and will appear wherever your platform surfaces notifications.