> ## Documentation Index
> Fetch the complete documentation index at: https://docs.foxreach.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> Receive real-time notifications when events happen in your FoxReach account.

## What Are Webhooks?

Webhooks let you receive real-time HTTP notifications when events occur in your FoxReach account. Instead of polling the API for changes, you register a URL and we'll send a POST request to it whenever something happens.

## How It Works

<Steps>
  <Step title="Register a webhook">
    Use the API to create a webhook with your endpoint URL and the events you want to subscribe to.
  </Step>

  <Step title="Receive events">
    When a subscribed event occurs, we send a POST request to your URL with the event payload.
  </Step>

  <Step title="Verify and process">
    Verify the webhook signature to confirm it came from FoxReach, then process the event.
  </Step>
</Steps>

## Creating a Webhook

```bash theme={null}
curl -X POST https://api.foxreach.io/api/v1/webhooks \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/outreach",
    "events": ["email.sent", "reply.received", "campaign.completed"]
  }'
```

**Response:**

```json theme={null}
{
  "data": {
    "id": "cwh_abc123",
    "url": "https://your-app.com/webhooks/outreach",
    "isActive": true,
    "events": ["email.sent", "reply.received", "campaign.completed"],
    "secret": "a1b2c3d4e5f6...",
    "consecutiveFailures": 0,
    "createdAt": "2025-01-15T10:00:00"
  }
}
```

<Warning>
  The `secret` is only returned when the webhook is first created. Save it securely — you'll need it to verify webhook signatures.
</Warning>

## Webhook Payload

When an event occurs, we send a POST request with a JSON body:

```json theme={null}
{
  "id": "cev_123",
  "type": "email.sent",
  "timestamp": "2025-01-15T10:30:00Z",
  "payload": {
    "emailLogId": "cel_123",
    "campaignId": "cmp_456",
    "leadId": "cld_789",
    "toEmail": "john@example.com",
    "fromEmail": "you@company.com",
    "subject": "Quick question about Acme"
  }
}
```

The request also carries `X-Webhook-Signature` (HMAC-SHA256 of the body), `X-Event-Type`, and `X-Event-Id` headers.

## Retry Policy

If your endpoint returns a non-2xx status code, we'll retry the delivery with exponential backoff. Each event is attempted up to **3 times in total** (the initial attempt plus 2 retries):

| Attempt   | Delay                                |
| --------- | ------------------------------------ |
| 1st retry | 60 seconds after the initial attempt |
| 2nd retry | 120 seconds after the 1st retry      |

If all 3 attempts fail, the delivery is marked failed and the webhook's `consecutiveFailures` counter increments — you can monitor this via the API. After 10 consecutive failed deliveries, the webhook is automatically disabled (`isActive: false`).

## Best Practices

* **Respond quickly** — return a `200` status code within 5 seconds. Process the event asynchronously if needed.
* **Handle duplicates** — webhook deliveries can occasionally be duplicated. Use idempotent processing.
* **Verify signatures** — always verify the HMAC-SHA256 signature to ensure the webhook came from FoxReach. See [Signature Verification](/webhooks/signatures).
* **Use HTTPS** — always use HTTPS endpoints for your webhook URLs.