SMS GatewayDocumentation

Webhooks

Webhooks allow you to receive real-time notifications when events occur on your SMS Gateway account — messages delivered, failures, OTP delivery, and more.

Overview

Instead of polling our API for status updates, you can register webhook endpoints that will receive HTTP POST requests whenever an event occurs. This enables real-time integrations with your systems, dashboards, and automation workflows.

Authentication

All webhook management endpoints require JWT authentication via the Developer API. Include your Bearer token in the Authorization header.

bash
1curl -X GET https://api.smsgateway.com/api/v1/developer/webhooks \
2  -H "Authorization: Bearer <your_jwt_token>"

Available Endpoints

GET
/api/v1/developer/webhooksList all webhooks
POST
/api/v1/developer/webhooksCreate webhook
PATCH
/api/v1/developer/webhooks/:idUpdate webhook
DELETE
/api/v1/developer/webhooks/:idDelete webhook
POST
/api/v1/developer/webhooks/:id/testTest webhook
GET
/api/v1/developer/webhooks/:id/deliveriesView delivery logs

Create a Webhook

Send a POST request with the following body to create a new webhook endpoint.

Request Body

name
required
string — A descriptive name for the webhook.
url
required
string — Your callback URL that will receive POST requests.
events
required
string[] — Event types to subscribe to (e.g. ["message.delivered"]).
secret
optional
string — Signing secret for HMAC-SHA256 signature verification.
create-webhook.sh
1{
2  "name": "My SMS Webhook",
3  "url": "https://your-server.com/webhooks",
4  "events": ["message.delivered", "message.failed"],
5  "secret": "whsec_your_signing_secret"
6}

Webhook Payload

Every webhook delivery sends a JSON payload to your endpoint with the event details.

payload.json
1{
2  "event": "message.delivered",
3  "payload": {
4    "messageId": "msg_9x8y7z6w5v",
5    "to": "+251911234567",
6    "from": "MyApp",
7    "status": "DELIVERED",
8    "deliveredAt": "2025-01-15T10:30:05.000Z"
9  },
10  "timestamp": "2025-01-15T10:30:05.000Z"
11}
idUnique identifier for this event.
eventThe event type (e.g. message.delivered).
timestampISO 8601 timestamp when the event occurred.
payloadEvent-specific details about the resource.

Signature Verification

When you provide a secret when creating a webhook, we sign the payload using HMAC-SHA256. The signature is included in the X-Webhook-Signature header.

verify.ts
1import crypto from 'crypto';
2
3function verifyWebhookSignature(
4  payload: string,
5  signature: string,
6  secret: string
7): boolean {
8  const expectedSignature = crypto
9    .createHmac('sha256', secret)
10    .update(payload, 'utf8')
11    .digest('hex');
12
13  const trusted = Buffer.from(`sha256=${expectedSignature}`, 'ascii');
14  const received = Buffer.from(signature, 'ascii');
15
16  return crypto.timingSafeEqual(trusted, received);
17}

Always verify webhook signatures in production to prevent spoofed requests. Use crypto.timingSafeEqual to prevent timing attacks.

Retry Policy

If your endpoint returns a non-2xx status code or times out (30 seconds), we will retry the delivery with exponential backoff:

  • Retry 1
    After 1 minute
  • Retry 2
    After 5 minutes
  • Retry 3
    After 30 minutes
  • Retry 4
    After 2 hours
  • Retry 5
    After 24 hours (final)

After 5 failed attempts, the webhook delivery is marked as failed and no further retries are attempted. You can view failed deliveries in the delivery logs.

Delivery Logs

Use the deliveries endpoint to view the delivery history for a specific webhook, including response codes, response times, and error messages.

bash
1curl -X GET https://api.smsgateway.com/api/v1/developer/webhooks/wh_abc123/deliveries \
2  -H "Authorization: Bearer <your_jwt_token>"

Related Pages

Webhook Event Types

View all available webhook events and their payload structures.

Error Codes

Understand API error responses and status codes.