Skip to main content

​
Webhooks

Webhooks allow you to receive real-time notifications when events occur in your account. Instead of polling the API, webhooks push data to your server when things happen.

​
How It Works

1

Configure Endpoint

Add a webhook endpoint URL in your Dashboard
2

Subscribe to Events

Choose which events you want to receive
3

Receive Events

Your server receives POST requests with event data
4

Acknowledge

Return 2xx status to confirm receipt

​
Event Format

All webhook events follow this structure: 
{
  "id": "evt_abc123",
  "type": "transaction.completed",
  "organizationId": "org_xyz",
  "createdAt": 1703520000000,
  "data": {
    "transactionId": "txn_123",
    "cardId": "card_456",
    "amount": 2500,
    "merchantName": "DoorDash"
  }
}

​
Event Types

​
Transactions

EventDescription
transaction.authorizedPending hold placed
transaction.completedTransaction settled
transaction.declinedTransaction rejected
transaction.reversedRefund processed

​
Cards

EventDescription
card.createdCard issued
card.frozenCard frozen
card.closedCard closed
card.expiredTTL reached

​
Agents

EventDescription
agent.createdAgent created
agent.suspendedAgent suspended
agent.limit_exceededSpending limit hit

​
Users

EventDescription
user.application.approvedKYC passed
user.application.deniedKYC failed
user.balance.updatedBalance changed

​
Deposits & Withdrawals

EventDescription
deposit.receivedFunds received
deposit.address_readyDeposit address available
withdrawal.submittedWithdrawal initiated
withdrawal.confirmedWithdrawal confirmed
withdrawal.failedWithdrawal failed

​
3DS

EventDescription
challenge.requestedOTP available

​
Disputes

EventDescription
dispute.createdChargeback initiated
dispute.resolvedChargeback resolved

​
Signature Verification

All webhooks include a signature for verification: Headers:
  • svix-id - Unique message ID
  • svix-timestamp - Unix timestamp
  • svix-signature - HMAC signature
Verification (Node.js): 
import { Webhook } from 'svix';

const webhook = new Webhook(process.env.WEBHOOK_SECRET);

app.post('/webhooks', (req, res) => {
  try {
    const payload = webhook.verify(
      req.body,
      {
        'svix-id': req.headers['svix-id'],
        'svix-timestamp': req.headers['svix-timestamp'],
        'svix-signature': req.headers['svix-signature']
      }
    );

    // Process the event
    console.log(payload.type, payload.data);

    res.status(200).send('OK');
  } catch (err) {
    res.status(400).send('Invalid signature');
  }
});

​
Retry Policy

Failed deliveries are retried with exponential backoff:
AttemptDelay
1Immediate
25 seconds
35 minutes
430 minutes
52 hours
65 hours
710 hours
824 hours
After 8 failed attempts, the event is marked as failed.

​
Best Practices

Process events asynchronously. Return 200 immediately, then process in background.
Use the id field to deduplicate. The same event may be delivered multiple times.
Always verify the webhook signature to ensure authenticity.
Your endpoint must use HTTPS in production.

​
Testing

Use the Dashboard to send test events to your endpoint:
  1. Go to Settings > Webhooks
  2. Select your endpoint
  3. Click Send Test Event
  4. Choose an event type