Webhooks & Callbacks

Real-Time Event Notifications

Webhooks let your application receive real-time notifications when events occur in your Sakura SMS account.

Setting Up Webhooks

• Go to Developer > Webhooks in the portal
• Add your endpoint URL (must be HTTPS)
• Copy the signing secret for payload verification

Available Events

• message.sent — SMS dispatched to carrier
• message.delivered — SMS confirmed delivered to recipient
• message.failed — SMS delivery failed
• campaign.completed — All messages in a campaign processed
• credits.low — Balance dropped below threshold
• contact.created — New contact added to your account

Payload Format

All webhook payloads are JSON with this structure:

• event — The event type (e.g., "message.delivered")
• timestamp — ISO 8601 timestamp
• data — Event-specific data (campaignId, recipient, status, etc.)

Verifying Signatures

Each webhook request includes an X-Sakura-Signature header. Verify it by computing HMAC-SHA256 of the request body using your signing secret.

Retry Policy

If your endpoint returns a non-2xx status, we retry up to 3 times with exponential backoff (30s, 5m, 30m). After 3 failures, the webhook is marked as failing.