Webhooks

Receive real-time notifications when message events occur.

Webhook Events

Message Events

• message.sent - Message accepted by carrier
• message.delivered - Message successfully delivered to recipient
• message.failed - Delivery failed
• message.bounced - Invalid number or carrier rejection
• message.opt_out - Recipient texted STOP to opt out
• message.opt_in - Recipient texted START/UNSTOP to opt back in

Verification Events

• verification.created - OTP code sent
• verification.delivered - SMS delivered to phone
• verification.verified - Code verified successfully
• verification.expired - Code expired without verification
• verification.failed - Max attempts exceeded
• verification.resent - OTP code resent

Webhook Payload

{
  "event": "message.delivered",
  "data": {
    "id": "msg_abc123",
    "to": "+15551234567",
    "from": "+18885551234",
    "text": "Hello!",
    "status": "delivered",
    "deliveredAt": "2026-01-22T12:01:30.000Z"
  },
  "timestamp": "2026-01-22T12:01:30.000Z",
  "apiVersion": "v1"
}

Security

Verify webhook signatures using HMAC-SHA256:

const crypto = require('crypto');

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

Retry Policy

Failed webhooks are retried with exponential backoff:

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