Webhooks

Receive real-time notifications when events occur in Beacon.

Setting Up Webhooks

1. Go to **Settings** > **Webhooks**
2. Click **"Add Endpoint"**
3. Enter your endpoint URL
4. Select events to subscribe to
5. Click **"Create"**

Available Events

Webhook Payload

All webhooks include:

{
  "event": "citation.new",
  "timestamp": "2024-01-15T10:30:00Z",
  "webhook_id": "wh_123",
  "data": {
    // Event-specific data
  }
}

Citation Event Example

{
  "event": "citation.new",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "citation_id": "cit_abc123",
    "brand_id": "brand_xyz",
    "platform": "chatgpt",
    "sentiment": "positive"
  }
}

Verifying Webhooks

All webhooks include a signature header:

X-Beacon-Signature: sha256=abc123...

Verify using your webhook secret:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}

Retry Policy

Failed webhooks are retried:

• 1st retry: 1 minute
• 2nd retry: 5 minutes
• 3rd retry: 30 minutes
• 4th retry: 2 hours
• 5th retry: 24 hours

After 5 failures, the endpoint is disabled.