Webhooks

Webhook Overview

Webhooks are optional. You can poll message status using GET /v1/messages/:messageId, or receive push updates on your webhook endpoint.

Webhook destination and subscribed events are configured in the Chatmaid dashboard.

Use a single API domain; environment is inferred from key prefix:

• https://developers-api.chatmaid.net + sk_test_* for sandbox behavior
• https://developers-api.chatmaid.net + sk_live_* for production behavior

Integration host: https://developers-api.chatmaid.net.

Events and Signatures

Supported events include:

• message.sent
• message.delivered
• message.read
• message.failed
• phone.connected
• phone.disconnected

Each webhook includes these headers:

• Content-Type: application/json
• X-Chatmaid-Event
• X-Chatmaid-Signature

# Webhook requests are sent by Chatmaid to your server.
# Use cURL locally only to simulate payload delivery to your endpoint:
curl -X POST https://your-receiver.example/webhooks/chatmaid \
  -H "Content-Type: application/json" \
  -H "X-Chatmaid-Event: message.delivered" \
  -H "X-Chatmaid-Signature: t=1700000000,v1=<signature>" \
  -d '{"event":"message.delivered","timestamp":"2026-02-06T14:20:00.000Z","data":{"messageId":"msg_abc123"}}'

Payloads

{
  "event": "message.delivered",
  "timestamp": "2026-02-06T14:20:00.000Z",
  "data": {
    "messageId": "msg_abc123def456",
    "from": "+15551234567",
    "to": "+15557654321",
    "status": "delivered",
    "environment": "live",
    "sentAt": "2026-02-06T14:19:12.000Z",
    "deliveredAt": "2026-02-06T14:19:15.000Z"
  }
}

Retries and Debugging

Failed webhook deliveries are retried up to 3 attempts with exponential backoff: 1 minute, 5 minutes, then 15 minutes after the initial attempt. Your endpoint should return HTTP 2xx quickly and process events asynchronously.