How webhooks work
1
Configure your endpoint
Register a webhook URL in your SmartRetry dashboard. This endpoint must be publicly accessible and respond to HTTPS POST requests.
2
Receive events
When a transaction event occurs (approval, decline, retry attempt, etc.), SmartRetry sends a JSON payload to your endpoint.
3
Acknowledge receipt
Return a
2xx status code within 30 seconds to confirm receipt. Any other response triggers a retry.Event types
Webhook payload
All webhook payloads follow a consistent structure:Unique identifier for this webhook event. Use this to deduplicate retried deliveries.
The event type. See Event types above.
ISO 8601 timestamp of when the event occurred.
Event-specific payload. Structure varies by event type but always includes relevant IDs.
Verifying webhook signatures
Every webhook request includes a signature header to verify the request originated from SmartRetry.t- Unix timestamp of when the signature was generatedv1- HMAC-SHA256 signature of the payload
Verification steps
Retry behavior
If your endpoint doesn’t return a2xx response, SmartRetry retries the delivery with exponential backoff:
After 7 failed attempts, the webhook is marked as failed. You can manually retry failed webhooks from the dashboard.
Best practices
-
Respond quickly - Return a
2xxresponse immediately and process the event asynchronously. If processing takes longer than 30 seconds, the request times out and triggers a retry. -
Idempotent handlers - Design your webhook handlers to safely process the same event multiple times. Use the
idfield as a deduplication key. -
Verify signatures - Always validate the
X-SmartRetry-Signatureheader before processing any webhook. - Use HTTPS - Webhook endpoints must use HTTPS. HTTP URLs are rejected.
- Handle all event types - Your handler should gracefully ignore event types it doesn’t recognize, allowing for future expansion.
Testing webhooks
In sandbox mode, you can trigger test webhook events from the dashboard:- Navigate to Settings > Webhooks
- Click Send test event
- Select an event type
- Review the payload delivered to your endpoint
Sandbox webhook events include
"environment": "sandbox" in the payload to distinguish them from production events.