SMS Callbacks & Delivery Reports

Salami Gateway handles delivery reports (DLRs) from SMS providers and forwards status updates to your application via configurable webhooks.

Provider Callback Endpoint

Providers send delivery reports and status updates to this endpoint:

ANY /api/sms/apps/{sms_app}/callback

Path Parameters

Authentication

No Bearer token required. This endpoint is called directly by SMS providers.

How It Works

1. Configure the callback/DLR URL in your SMS provider's dashboard:

   https://your-domain.com/api/sms/apps/{app_id}/callback
   

2. When a message status changes (sent, delivered, failed), the provider sends a notification.
3. Salami logs the raw request as an IPN record.
4. The driver parses the provider-specific payload and updates the Message record.
5. Events fire, triggering your configured webhooks and Slack notifications.

Status Codes

Provider DLR URL Configuration

Each provider requires you to set a callback URL. Examples:

Twilio

Set the "Status Callback URL" on your Twilio phone number or messaging service:

https://your-domain.com/api/sms/apps/{app_id}/callback

Africa's Talking

Set the delivery reports callback URL in the dashboard:

https://your-domain.com/api/sms/apps/{app_id}/callback

Vonage (Nexmo)

Set the DLR webhook in your Vonage application settings:

https://your-domain.com/api/sms/apps/{app_id}/callback

Infobip

Configure the notify URL when sending messages or in your Infobip account settings:

https://your-domain.com/api/sms/apps/{app_id}/callback

MessageBird

Set the status report URL in your MessageBird dashboard:

https://your-domain.com/api/sms/apps/{app_id}/callback

Configuring Your Webhooks

Webhooks forward message events from Salami to your application. Configure webhooks through the web dashboard under SMS > Apps > [Your App] > Webhooks.

Webhook Fields

Webhook Filtering

Webhooks support conditional filtering. Only messages matching your criteria trigger the webhook.

Examples:

• Fire on all incoming messages:

  • field: folder, comparator: equals, keyword: inbox

• Fire on all delivered messages:

  • field: status, comparator: equals, keyword: delivered

• Fire on messages containing a keyword:

  • field: message, comparator: contains, keyword: SUBSCRIBE

• Fire on messages from a specific number:

  • field: from, comparator: equals, keyword: 254712345678

Available Comparators

Available Message Fields for Matching

Webhook Payload Format

When a webhook fires, Salami sends a POST request to your callback_url.

Headers

Body (Message Webhook)

{
  "id": 156,
  "to": "254712345678",
  "from": "+15551234567",
  "message": "Hello! Your order #1234 has been confirmed.",
  "sms_provider": "Twilio",
  "provider_id": "SM1234567890abcdef",
  "message_time": "2026-03-15T14:30:00.000000Z",
  "telco_code": "63902",
  "telco_name": "Safaricom",
  "message_parts": 1,
  "retry_count": 0,
  "status": "delivered",
  "delivery_date": "2026-03-15T14:30:05.000000Z",
  "cost": "0.0075",
  "folder": "outbox",
  "channel": "sms",
  "app_id": 1,
  "created_by": 1,
  "created_at": "2026-03-15T14:30:00.000000Z",
  "updated_at": "2026-03-15T14:30:05.000000Z"
}

Body (Call Webhook)

For voice-enabled apps, call events also trigger webhooks:

{
  "id": 1,
  "from": "254712345678",
  "to": "+15551234567",
  "duration": 45,
  "status": "completed",
  "app_id": 5,
  "created_at": "2026-03-15T16:00:00.000000Z"
}

Verifying Webhook Signatures

If you configure a webhook_secret, verify the X-SALAMI-SIGNATURE header.

Verification Steps

1. Read the X-SALAMI-SIGNATURE header.
2. Compute HMAC-SHA256 of the raw JSON body using your webhook secret.
3. Compare the computed hash with the header value.

Example (PHP)

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SALAMI_SIGNATURE'];
$secret = 'your-webhook-secret';

$computed = hash_hmac('sha256', $payload, $secret);

if (hash_equals($computed, $signature)) {
    // Valid -- process the webhook
} else {
    // Invalid -- reject
    http_response_code(401);
    exit;
}

Example (Node.js)

const crypto = require('crypto');

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

Retry Behavior

Failed webhook dispatches are automatically retried.

A webhook dispatch is considered failed if:

• The endpoint returns a non-2xx HTTP status code
• The request times out
• A network error occurs

Webhook Logs

All dispatch attempts are logged and viewable in the dashboard under SMS > Apps > [Your App] > Webhook Logs. Each log entry includes:

• Target URL
• HTTP response status code
• Response body
• Timestamp
• Success/failure indicator

Slack Notifications

In addition to webhooks, configure Slack notifications for real-time alerts under SMS > Apps > [Your App] > Slack Integrations.

Slack notifications are triggered for:

• Incoming IPN requests (raw provider callbacks)
• Sent messages
• Received messages
• Call events
• Device status changes (for MSync phone gateways)

Status Update Flow

Message Created (status: pending)
    |
    v
Provider Accepts (status: sent)
    |
    v
DLR Arrives at /api/sms/apps/{app}/callback
    |
    v
Driver Parses DLR --> Updates Message (status: delivered/failed)
    |
    v
Webhooks Dispatched to Your Endpoints
    |
    v
Slack Notifications Sent

Related Documentation

• SMS API Overview
• Sending Messages
• Receiving Messages
• SMS Apps
• Providers