Skip to main content

​
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

1

Register a webhook

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

Receive events

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

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: 
{
  "event": "email.sent",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "emailLogId": "cel_123",
    "campaignId": "cmp_456",
    "leadId": "cld_789",
    "toEmail": "[email protected]",
    "fromEmail": "[email protected]",
    "subject": "Quick question about Acme"
  }
}

​
Retry Policy

If your endpoint returns a non-2xx status code, we’ll retry the delivery with exponential backoff. After consecutive failures, the webhook will be marked as unhealthy.
AttemptDelay
1st retry1 minute
2nd retry5 minutes
3rd retry30 minutes
After 3 consecutive failures, the webhook’s consecutiveFailures counter increments. You can monitor this via the API.

​
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.