Skip to main content
Webhooks let SmartRetry push event notifications to your server in real time. Instead of polling the status endpoint, you receive an HTTP POST request whenever a transaction’s state changes.

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:
id
string
required
Unique identifier for this webhook event. Use this to deduplicate retried deliveries.
type
string
required
The event type. See Event types above.
created_at
string
required
ISO 8601 timestamp of when the event occurred.
data
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.
The signature header contains:
  • t - Unix timestamp of when the signature was generated
  • v1 - HMAC-SHA256 signature of the payload

Verification steps

Always verify webhook signatures before processing events. Never trust the payload without verification.

Retry behavior

If your endpoint doesn’t return a 2xx 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.
Use the id field to deduplicate webhook deliveries. The same event may be delivered multiple times if your endpoint returned an error or timed out.

Best practices

  1. Respond quickly - Return a 2xx response immediately and process the event asynchronously. If processing takes longer than 30 seconds, the request times out and triggers a retry.
  2. Idempotent handlers - Design your webhook handlers to safely process the same event multiple times. Use the id field as a deduplication key.
  3. Verify signatures - Always validate the X-SmartRetry-Signature header before processing any webhook.
  4. Use HTTPS - Webhook endpoints must use HTTPS. HTTP URLs are rejected.
  5. 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:
  1. Navigate to Settings > Webhooks
  2. Click Send test event
  3. Select an event type
  4. Review the payload delivered to your endpoint
Sandbox webhook events include "environment": "sandbox" in the payload to distinguish them from production events.