Automation & Integrations
Process webhooks durably, acknowledge them quickly, deduplicate delivery, retry work safely, and use scheduled checks to recover missed events.
How the workflow connects
A webhook endpoint should not attempt the entire business workflow before responding. Providers retry, events arrive out of order, and downstream systems become unavailable. An event inbox separates receipt from processing and lets a polling or reconciliation job recover what delivery alone cannot guarantee.
Verify the signature against the raw request, capture the provider and event identifier, store the payload or permitted subset, and return within the provider's expected window. Use a unique constraint on provider, connection, and event ID to make repeated delivery harmless.
Sensitive payloads need retention and access rules. Store only what processing and audit requirements justify.
Workers can claim pending events with an attempt count and lease time, then mark them processed, retryable, or needs review. Keep the business record or action identifier beside the event. A failed worker can release the lease without losing the original delivery.
A customer-updated event may arrive before customer-created, or a payment-refunded event may repeat after completion. Load the current authoritative state and apply transitions idempotently. When sequence matters, compare provider versions or retrieve the latest resource instead of trusting arrival order.
Run a scheduled query for records changed since a safe checkpoint, with an overlap window. Compare them with locally processed versions and enqueue missing work through the same handler. Also flag events that remain pending beyond the normal processing window.
A payment provider sends an event indicating that an invoice was paid. The endpoint verifies the request signature using the raw body, writes the event to an inbox under the provider event ID, and responds. A worker later claims the event, retrieves the current payment when required, checks whether the invoice is already paid, and applies the transition once.
If the accounting system is unavailable, the event remains retryable without asking the provider to redeliver it. If the same webhook arrives again, the uniqueness rule points to the existing inbox record. If a refund event arrived first, current-state validation and a provider lookup prevent the later payment event from incorrectly reopening the invoice.
Visual guide
The public endpoint does only the work required to trust and retain the event; business processing happens behind a durable boundary.
Verify
Check signature, source, timestamp, and permitted payload size.
Store
Persist the raw event or approved subset under a scoped unique ID.
Acknowledge
Return promptly after durable receipt rather than after every downstream action.
Process
Claim, validate current state, and apply the business transition idempotently.
Recover
Retry temporary failures and poll for missing changes.
Signature verification is only one control. Limit request size, accept expected content types, reject unsupported event types, protect secrets, and avoid logging sensitive payloads by default. If events contain personal or payment-related information, define who can view them and when raw bodies are redacted or deleted.
Operational reporting should distinguish invalid deliveries, accepted events, processing failures, retries, dead-letter items, and reconciliation discoveries. Alert on a sustained backlog or an event that exceeds its processing target; do not page someone for every individual retry. A review screen should provide the event, linked business record, last error, attempt history, and safe next actions.
Practical questions
Return success when verification and durable receipt succeed. Return an appropriate error when the request cannot be trusted or stored so the provider can follow its documented retry policy.
Retention depends on debugging, audit, privacy, and provider terms. Define a period and remove or redact sensitive data that is no longer needed.
Continue exploring
Work with Sun Cluster
Sun Cluster builds API and webhook integrations with durable processing, safe retries, observability, and recovery paths.
