# 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

| Event Type | Description |
|  --- | --- |
| `merchant.created` | Triggered when a new merchant is created |
| `merchant.updated` | Triggered when merchant information is updated |
| `merchant.verification_failed` | Triggered when merchant verification fails |
| `merchant.verification_approved` | Triggered when merchant verification is approved |
| `merchant.processing` | Triggered when merchant starts processing |
| `merchant.deactivated` | Triggered when a merchant is deactivated |


### Charge Events

| Event Type | Description |
|  --- | --- |
| `charge.succeeded` | Triggered when a charge is successfully processed |
| `charge.failed` | Triggered when a charge fails |


## Webhook Payload Structure

All webhook events follow this standard structure:


```json
{
  "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)


```javascript
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