Webhooks

Overview

Webhooks allow you to receive real-time notifications when events occur in your account. When an event happens, we'll send an HTTP POST request to the URL you've configured with the event data.

Event Types

Merchant Events

Charge Events

Webhook Payload Structure

All webhook events follow this standard structure:

{
  "id": "evt_1234567890abcdef",
  "object": "merchant",
  "api_version": "2024-07-06",
  "created": "2024-01-15T10:30:00Z",
  "type": "merchant.created",
  "data": {
    "created_at": "2024-01-15T10:30:00Z",
    "account_sid": "acc_1234567890abcdef",
    "event_type": "merchant.created",
    "object": {
      "id": "merchant_1234567890abcdef",
      "object": "merchant",
      "payload": {
        // Event-specific data
      }
    },
    "api_version": "2024-07-06",
    "request": {
      "id": "req_1234567890abcdef"
    }
  }
}

Payload Fields

• id: Unique identifier for the event
• object: Type of object the event relates to (merchant, charge, etc.)
• api_version: API version used when the event was created
• created: ISO 8601 timestamp when the event was created
• type: The event type (see Event Types above)
• data: Event-specific data containing the full event payload
• data.request.id: ID of the API request that triggered the event (null for automatic events)

Security

Webhook Signatures

Each webhook request includes a signature that you can use to verify the request came from our servers.

Signature Generation:

• Algorithm: HMAC-SHA256
• Secret: Your webhook's signing secret (provided when creating the webhook)
• Payload: The raw JSON body of the request

Verification Process:

1. Extract the signature from the request headers
2. Compute HMAC-SHA256 of the request body using your webhook secret
3. Compare the computed signature with the received signature

Example Verification (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return computedSignature === signature;
}

Delivery and Retries

• Timeout: Webhook requests timeout after 8 seconds
• Retries: Failed webhooks are automatically retried
• Status Tracking: All webhook deliveries are logged with status and response details
• Custom Headers: You can configure custom HTTP headers for your webhook endpoints

Best Practices

1. Idempotency: Handle duplicate events gracefully using the event ID
2. Respond Quickly: Return a 2xx status code as quickly as possible
3. Verify Signatures: Always verify webhook signatures for security
4. Handle Failures: Implement proper error handling and logging
5. Use HTTPS: Always use HTTPS URLs for webhook endpoints