Skip to main content
DocsAPIWebhooks

Webhooks

Receive real-time HTTP notifications when events happen in your BeeCastly account.

Available Events

message.sentA message was sent successfully
message.deliveredA message was delivered to the recipient
message.readA message was read by the recipient
message.failedA message delivery failed
message.receivedAn inbound message was received
contact.createdA new contact was created
contact.updatedA contact was updated
campaign.sentA campaign finished sending
campaign.completedAll delivery reports received for a campaign
form.submittedA form submission was received
payment.receivedA payment was received on an invoice

Webhook Payload

POST https://your-server.com/webhooks/beecastly
Content-Type: application/json
X-BeeCastly-Signature: sha256=abc123...

{
  "event": "message.delivered",
  "timestamp": "2025-03-26T10:00:00Z",
  "data": {
    "messageId": "msg_abc123",
    "conversationId": "conv_def456",
    "contactId": "contact_ghi789",
    "channel": "WHATSAPP",
    "status": "DELIVERED",
    "deliveredAt": "2025-03-26T10:00:00Z"
  }
}

Setup

  1. Go to Settings → Webhooks (or use the API)
  2. Add your endpoint URL (must be HTTPS)
  3. Select which events to subscribe to
  4. Save — BeeCastly will send a test ping to verify your endpoint
  5. Your endpoint should return 200 OK within 5 seconds

Signature Verification

Every webhook includes an X-BeeCastly-Signature header for verification.

Compute HMAC-SHA256(webhook_secret, request_body) and compare with the header value.

// Node.js verification example
const crypto = require('crypto');

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

Retry Policy

If your endpoint returns a non-2xx status, BeeCastly will retry up to 3 times with exponential backoff (1min, 5min, 30min). After 3 failures, the webhook is paused.