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:string
required
Unique identifier for this webhook event. Use this to deduplicate retried deliveries.
string
required
The event type. See Event types above.
string
required
ISO 8601 timestamp of when the event occurred.
object
required
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.