Retry Policy

At-least-once delivery

Webhooks are delivered at-least-once. A delivery may arrive more than once. Always dedupe on event_key before performing side-effects (crediting a wallet, fulfilling an order, marking a payout done).

Retry schedule

If your endpoint returns a non-2xx status or does not respond within 10 seconds, OuiPay retries with exponential backoff:

After 7 failed attempts, the delivery is marked terminal.

Auto-disable

A subscription that accumulates consecutive failures past its threshold is automatically disabled. The consecutive_failures counter on the subscription object tracks the current count.

Once disabled:

• No further deliveries are attempted.
• Events that fire while the subscription is disabled are not queued.
• Re-enable the subscription from the dashboard after fixing your endpoint.

What counts as success

Your endpoint must return a 2xx HTTP status within 10 seconds. The response body is ignored.

• 200, 201, 202, 204: all count as success.
• 301, 302 redirects: OuiPay does not follow redirects. Return 2xx directly.
• 4xx: counted as a failure (your endpoint rejected the delivery).
• 5xx: counted as a failure.
• Timeout (>10 seconds): counted as a failure.

Best practice: ack fast, process async

Return 200 immediately and push the event to a queue for processing. A slow endpoint triggers retries and can cause the same event to be delivered multiple times.

Receive → Verify → Dedupe → Ack 200 → Queue → Process

Do not perform database writes, external API calls, or other slow operations in the request handler.

Redelivery

You can manually redeliver a specific event from the dashboard or via the API:

curl -X POST https://api.ouipay.com/v1/webhooks/deliveries/01M2S18.../redeliver \
  -H "Authorization: Bearer sk_test_..."

This queues a fresh delivery attempt for the event.