Callback Retry Mechanism

Exirom uses webhook callbacks to notify your system of transaction status changes. If a callback delivery fails, the system automatically retries using exponential backoff.

#How It Works

When a transaction reaches a terminal status, Exirom sends an HTTP POST to your configured callback URL. If your endpoint returns a non-2xx response or the request times out, the callback is stored and scheduled for retry.

Only terminal transaction statuses trigger retry storage. Intermediate status updates that fail delivery are not retried.

#Retry Schedule

A failed callback is retried up to 11 times. The first retry runs about 5 seconds after the failed delivery; after that, each retry waits twice as long as the previous one, starting at 2 minutes.

Retries are sent by a job that runs every 2 minutes, so each retry can go out up to 2 minutes later than scheduled. If the 11th retry fails, the callback is not retried again — poll the transaction status instead.

#Scope

The callback retry mechanism applies to all webhook-enabled operations:

• Card payments
• Card payouts
• Card refunds
• APM payments
• APM payouts

#Best Practices

• Respond 200 OK immediately — do heavy processing asynchronously after returning the response
• Deduplicate card refunds on original-payment transactionId + signed requestId + transactionStatus; other callbacks use transaction ID + status
• Implement a polling fallback via GET /v1/payments/card/info/{id} for critical transactions if your endpoint was unavailable (returns declineCode on failure)
• Always verify the X-Checksum header before processing

For code examples covering each of these patterns, see Webhook Best Practices.