ChatPulse

Webhooks Documentation

ChatPulse uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when an email is delivered, a message bounces, or a user replies to your WhatsApp message.

Events

We currently support the following webhook events:

  • message.delivered - Triggered when a WhatsApp message or Email is successfully delivered.
  • message.read - Triggered when the recipient reads your WhatsApp message.
  • message.failed - Triggered when a message fails to deliver (bounces, invalid number, etc).
  • message.received - Triggered when an inbound WhatsApp message is received.

Securing Webhooks

To ensure that the webhooks you receive are actually sent from ChatPulse, we include a X-ChatPulse-Signature header with every request.

The signature is a HMAC-SHA256 hash generated using your Webhook Secret and the raw payload body.

Verification Example (Node.js)

verify.ts
import crypto from 'crypto';const WEBHOOK_SECRET = process.env.CHATPULSE_WEBHOOK_SECRET;export function verifySignature(payload: string, signature: string): boolean {  const expectedSignature = crypto    .createHmac('sha256', WEBHOOK_SECRET)    .update(payload)    .digest('hex');  return crypto.timingSafeEqual(    Buffer.from(signature),    Buffer.from(expectedSignature)  );}

Payload Structure

All webhook events follow a standard JSON envelope structure.

{  "id": "evt_123456",  "type": "message.delivered",  "created_at": "2023-10-15T12:00:00Z",  "data": {    "message_id": "msg_abc123",    "channel": "whatsapp",    "to": "+1234567890"  }}