Idempotency & retries

Ionic delivers webhook events at least once and does not guarantee arrival order. Your application owns processing, persistence, and business effects. These contracts define what a receiver can rely on.

​

Event and delivery identity

A duplicate event is not a new payment. Different events can also describe the same resource, so event deduplication alone does not establish that a business action has happened only once. An application reference does not establish ownership; the merchant, mode, and resource identity remain part of that boundary.

​

Acknowledgment and retries

A 2xx response acknowledges the delivery. Ionic stops retrying that delivery once acknowledgment is received. A timeout, unreachable endpoint, or non-2xx response can result in another delivery with the same event ID and delivery ID. Acknowledgment must mean that the event has been durably accepted under your application’s processing contract. Merely starting background work or recording an ID as processed does not establish that the work completed. Your application must be able to recover accepted work after a crash and handle redelivery after a lost acknowledgment. Signature verification uses the exact raw body and the incoming signature headers. An invalid signature must not be treated as an authenticated event. A valid signature still requires the expected merchant, mode, and resource association before a payment result is applied.

​

Arrival order and current state

data.object is a snapshot at event creation time. It may be older than the state your application has already observed. Delivery order and timestamps do not define a total ordering of all resource changes. The resource’s retrieval endpoint returns its current state. A delayed failure event does not by itself establish that a previously successful payment is now failed. Your application decides how to reconcile snapshots with current state.

​

Recovery after an outage

Webhook endpoint management exposes whether an endpoint is disabled and allows it to be re-enabled. Re-enabling an endpoint does not by itself prove that every missed business effect has been recovered. Existing resources can change during an outage, so listing only resources created during that outage is insufficient. Resource IDs and event IDs identify different things and cannot be compared as equivalent records. The relevant resource retrieval and list APIs provide state for your application’s recovery process.

​

What’s next