Webhooks Overview - FoxReach API

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

Use the API to create a webhook with your endpoint URL and the events you want to subscribe to.

Receive events

When a subscribed event occurs, we send a POST request to your URL with the event payload.

Verify and process

Verify the webhook signature to confirm it came from FoxReach, then process the event.

Creating a Webhook

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:

{
  "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"
  }
}

The secret is only returned when the webhook is first created. Save it securely — you’ll need it to verify webhook signatures.

Webhook Payload

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

{
  "id": "cev_123",
  "type": "email.sent",
  "timestamp": "2025-01-15T10:30:00Z",
  "payload": {
    "emailLogId": "cel_123",
    "campaignId": "cmp_456",
    "leadId": "cld_789",
    "toEmail": "[email protected]",
    "fromEmail": "[email protected]",
    "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.
Use HTTPS — always use HTTPS endpoints for your webhook URLs.

​What Are Webhooks?

​How It Works

​Creating a Webhook

​Webhook Payload

​Retry Policy

​Best Practices

What Are Webhooks?

How It Works

Creating a Webhook

Webhook Payload

Retry Policy

Best Practices