Webhook Setup & Testing

Real-Time Event Notifications

Webhooks push real-time event data to your server when things happen on Sakura SMS — message delivered, payment received, contact opted out, etc.

Creating a Webhook

• Go to Developer API > Webhooks
• Click Add Webhook
• Enter your endpoint URL (must be HTTPS)
• Select which events to subscribe to
• Save and activate

Available Event Types

• message.sent — Message submitted to gateway
• message.delivered — Delivery confirmed by network
• message.failed — Delivery failed (with error code)
• message.received — Inbound message received
• credit.purchased — Credits added to account
• credit.low — Balance below threshold
• contact.opted_out — Contact sent STOP

Payload Format

All webhook payloads are JSON with this structure:

{
  "event": "message.delivered",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "message_id": "msg_abc123",
    "phone": "255712345678",
    "status": "delivered",
    "sender_id": "SAKURA"
  }
}

Signature Verification

Every webhook request includes an X-Sakura-Signature header. Verify it to ensure the request came from Sakura SMS:

• Compute HMAC-SHA256 of the raw request body using your webhook secret
• Compare the result with the signature header
• Reject requests that don't match

Testing Webhooks

• Use the Test button next to each webhook to send a sample payload
• Use webhook.site as a temporary endpoint during development
• Check the webhook delivery log for request/response details and retry history

Retry Policy

• Failed deliveries are retried 3 times with exponential backoff (1 min, 5 min, 30 min)
• Webhooks returning non-2xx status codes are marked as failed
• Consistently failing webhooks are automatically disabled after 24 hours