%201.svg)
How to Build Reliable Chargeback Webhooks: Idempotency, Retries and Duplicate Events
Chargebacks?
Não é mais problema seu.
Recupere 4 vezes mais chargebacks e PREVENÇÃO — até 90% dos e-mails recebidos —, com tecnologia de IA e uma rede global Rede de 20.000 Lojistas.
Mais de 600 avaliações
Resumo:
- Verify the signature using the provider’s documented signing construction, persist the event before acknowledging it and process it asynchronously. Deduplicate using a documented immutable event or delivery ID where available, protect downstream actions separately and reconcile local state with the provider API.
- Design for state convergence, not event order.
Verify the signature using the provider’s documented signing construction, persist the event before acknowledging it and process it asynchronously. Deduplicate using a documented immutable event or delivery ID where available, protect downstream actions separately and reconcile local state with the provider API.
A duplicate dispute event can trigger two evidence jobs, two merchant notifications or two financial entries. A lost event can hide a dispute until its response window is nearly over. Webhook handling therefore belongs in the reliability design, not only the integration controller.
The receiver should be small and predictable. Authentication, durable receipt and acknowledgment happen first. Business processing happens after the event is safely stored.
At a glance
- 1. Authenticate
Verify the provider signature using its documented signing construction; preserve the request data that verifier requires.
- 2. Persist
Store provider and account scope, documented receipt identity or version, type, protected payload, receipt time and authentication result.
- 3. Acknowledge
Return a successful response after durable receipt, not after all downstream work.
- 4. Deduplicate
Use a documented delivery identity with provider and account scope; define a resource-version fallback when the schema lacks a delivery ID.
Authenticated duplicate already stored → acknowledge without repeating work. New receipt → process asynchronously, retry safely and reconcile provider state.
Use documented resource versions and valid state transitions; retrieve current provider state when ordering is ambiguous.
Retry transient processing failures with bounded backoff and dead-letter handling.
Compare provider state and local state on a schedule to find missed events.
Assume at-least-once delivery
Webhook providers retry when they do not receive a successful acknowledgment. Networks and proxies can also leave the sender uncertain whether a request completed. HTTP semantics explain why repeating a non-idempotent operation without a safety mechanism can create duplicate effects.
Design the consumer so processing the same event more than once produces the same durable state. A unique event record is the first guard. Idempotency at each downstream action is the second.
Verify the provider signature before business processing
Signature verification should use the raw request body and the correct secret for the environment or platform account. Reject requests outside the accepted timestamp window when the provider includes one. Rotate secrets through an overlap period rather than replacing them without coordination.
For Chargeflow, the documented HMAC construction combines the HTTP method, request path and serialized body, using the API Secret Key. Follow that exact construction rather than assuming a raw-body-only hash. Keep access and signing keys separate and compare signatures in constant time.
Do not log secrets or full payloads indiscriminately. Store enough structured metadata and a protected payload copy to support replay and investigation.
Separate receipt from processing
The HTTP handler should validate, persist and acknowledge quickly. A worker can then resolve the merchant, update the canonical dispute, trigger evidence or notify the merchant. This prevents slow dependencies from causing provider retries and duplicate deliveries. Preserve merchant ownership through the worker and export boundaries.
Use an inbox table or durable queue with event status, attempt count and last error. A transaction should insert the event and enqueue or mark it ready atomically so an accepted event cannot disappear between those operations.
Handle ordering with state rules
Events may arrive out of order, especially after retries or a temporary outage. Do not trust receipt order. Compare source timestamps or versions and apply only valid state transitions. Preserve every event even when it does not change the current projection. Keep the original source alongside the canonical dispute state.
A timestamp alone may not establish a total order. When versions are absent or ordering is ambiguous, retrieve the current provider resource and apply explicit transition rules instead of guessing from arrival time.
Chargeflow regeneration can emit another evidence-ready event for the same evidence ID with a higher file version. Compare evidence versions separately from receipt deduplication; the evidence resource ID alone must not suppress a newer package.
Reconciliation is part of webhook reliability
Even a well-designed webhook consumer can miss an event because of configuration, expired credentials or provider-side failure. A scheduled job should query recent disputes or evidence records and compare them with local state. Financial effects need their own reconciliation and duplicate-posting controls.
Monitor age of the oldest unprocessed event, delivery failures, signature failures, duplicate rate, dead-letter count and time since the last successful event per merchant integration. A silent connector is more dangerous than a visible error.
Implementation sequence
Preserve the request data needed by the provider’s documented signature verifier.
Verify the provider signature, environment and structure; check a signed timestamp only where supported.
Use a documented immutable event or delivery ID with provider and account scope; define a fallback when absent.
Return success after durable storage, including for a known duplicate.
Resolve tenant, apply transition rules and perform idempotent downstream actions.
Use bounded exponential backoff, classify permanent failures and dead-letter exhausted events.
Poll recent provider records on a schedule and repair missing local events.
Replay saved fixtures and confirm no duplicate notification, evidence job or ledger entry occurs.
Failure modes and controls
| Failure mode | Business consequence | Control |
|---|---|---|
| Business work before acknowledgment | Slow dependencies cause provider retries and duplicates. | Persist first and process asynchronously. |
| Deduplicating by dispute ID | Legitimate later events for the same dispute are discarded. | Deduplicate by provider event ID and version projections separately. |
| Returning an error for duplicates | The provider keeps retrying a successfully stored event. | Acknowledge known duplicates as successful receipt. |
| Blind last-write-wins | An old event moves a case backward. | Apply source versions and allowed transition rules. |
| No reconciliation job | A missing event remains invisible until a merchant complains. | Compare local and provider state regularly. |
Scroll horizontally when all columns do not fit.
Design for state convergence, not event order
Webhook delivery is an alert that something may have changed, not a guaranteed ordered transaction log. A reliable handler converges the local case to the provider’s current state even when events arrive twice, arrive late or arrive out of order.
Verify the provider signature before queuing business work.
Store the documented delivery identity or explicit fallback, receipt time and protected payload before acknowledging.
Return success for an authenticated event already stored instead of repeating downstream work.
Complete the HTTP response quickly, then process with bounded retries, backoff and jitter.
When the provider supports it, fetch the latest dispute object rather than trusting event sequence.
Update only when the incoming or fetched state advances the case under explicit state rules.
Move repeatedly failing events to a visible queue with replay controls and an owner.
Periodically compare provider cases with the local store to find events that were never received.
OWASP recommends signature verification, event deduplication and downstream idempotency; Checkout.com also warns that webhook retries can create duplicate deliveries. The operational runbook should therefore test duplicates, delayed events and replay as normal conditions.
Evidence base: OWASP Webhook Security Cheat Sheet; Checkout.com duplicate webhook guidance.
How Chargeflow Connect fits
Chargeflow's platform webhook catalog includes evidence-ready, evidence-error, integration-access-error and dispute-created events. The documentation calls for signature verification and describes versioned evidence events and expiring download URLs.
The current documentation lists dispute.created but no dispute-update event. Later status changes and final outcomes require API reconciliation. The evidence-ready schema exposes account, dispute, evidence and version fields; it does not establish an immutable delivery ID. Confirm the actual event schema before choosing the receipt key.
Platforms should store permanent resource IDs rather than temporary file links, process every event through a durable inbox and monitor integration-access errors as merchant-facing action items.
Current evidence links expire seven days after issue. Store the evidence ID, retrieve a fresh URL when needed and retain the exact downloaded version used for submission.
Build a reliable event-driven dispute workflow with Chargeflow Connect webhooks.
Perguntas frequentes
Should a webhook endpoint return success before processing finishes?
Yes, after the event has been authenticated and durably stored. Downstream processing should normally be asynchronous.
What is the best idempotency key for a webhook?
Use a documented immutable event or delivery ID with the provider and account namespace when available. If the event schema has no such ID, define deduplication from its documented resource version and guard each downstream action; do not mistake a webhook configuration ID for a unique delivery ID.
How should duplicate webhooks be answered?
Return the normal successful acknowledgment after confirming the event is already stored.
What if events arrive out of order?
Preserve them and update current state only when the source version, time and transition rules allow it.
Are webhooks enough for synchronization?
No. Use periodic reconciliation against the provider API to detect configuration problems and missed events.
Fontes
Chargeflow platform webhook events
Chargeflow Platforms quickstart
Related platform guides
Add Chargeback Management to Your Platform
Use a platform-first integration to offer chargeback automation across your merchant base.
Chargebacks?
Não é mais problema seu.
Recupere 4 vezes mais chargebacks e PREVENÇÃO — até 90% dos e-mails recebidos —, com tecnologia de IA e uma rede global Rede de 20.000 Lojistas.
.png)
