SMS Status Webhooks

Overview

SMS Status Webhooks let you receive real-time notifications when outbound SMS messages change status — for example when a message is Sent, Delivered, or Failed. Instead of polling the API, you register a webhook URL and the platform pushes status updates to you automatically.

This is a v2-only feature available at api/v2/status-webhooks.

Prerequisites

• An active Tech231 Platform account with API v2 access
• A publicly accessible HTTP or HTTPS endpoint to receive callbacks
• Valid authentication token (JWT) with your tenant

Quick Start

1. Register a Webhook

Code
curl -X POST https://sms-api.tech231apps.net/api/v2/status-webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourapp.com/sms-status",
    "secret": "whsec_your_secret_key",
    "name": "Production Status Hook"
  }'

2. Receive Status Updates

The platform will call your endpoint whenever a message reaches Sent, Delivered, or Failed status:

Code
POST /sms-status HTTP/1.1
Host: api.yourapp.com
Content-Type: application/json
X-Hub-Signature-256: sha256=abc123...

{
  "messageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenantId": "your-tenant-id",
  "status": "Delivered",
  "senderId": "MyApp",
  "recipient": "+231770001234",
  "timestamp": "2026-02-23T14:30:00.000Z",
  "providerMessageId": "prov-msg-001",
  "failureReason": null
}

3. Verify the Signature

If you provided a secret, validate the X-Hub-Signature-256 header:

Code
const crypto = require('crypto');

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

Managing Subscriptions

You can create multiple webhook subscriptions per tenant — each with its own URL, HTTP method, and template configuration.

Create Subscription

Code
POST /api/v2/status-webhooks

Request Body:

Response: 201 Created

Code
{
  "subscriptionId": "a1b2c3d4e5f6",
  "tenantId": "your-tenant-id",
  "url": "https://api.yourapp.com/sms-status",
  "hasSecret": true,
  "isActive": true,
  "name": "Production Status Hook",
  "httpMethod": "POST",
  "bodyTemplate": null,
  "queryParamTemplate": null,
  "statusMappings": null,
  "createdAt": "2026-02-23T10:00:00Z",
  "updatedAt": null
}

Update Subscription

Code
PUT /api/v2/status-webhooks/{subscriptionId}

Request Body:

Get Subscription

Code
GET /api/v2/status-webhooks/{subscriptionId}

List All Subscriptions

Code
GET /api/v2/status-webhooks

Delete Subscription

Code
DELETE /api/v2/status-webhooks/{subscriptionId}

Default Payload

When no custom templates are configured, the platform sends a JSON payload via POST:

Code
{
  "messageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenantId": "your-tenant-id",
  "status": "Delivered",
  "senderId": "MyApp",
  "recipient": "+231770001234",
  "timestamp": "2026-02-23T14:30:00.000Z",
  "providerMessageId": "prov-msg-001",
  "failureReason": null
}

Payload Fields

Template Placeholders

You can customize how the webhook request is formatted using body templates and query parameter templates. Templates use double-brace {{Variable}} placeholders that are replaced with actual values at delivery time.

Available Placeholders

Status Mappings

By default, the {{Status}} placeholder resolves to the platform's internal status values: Sent, Delivered, or Failed. If your system uses different status terminology, you can provide a statusMappings dictionary to automatically translate these values.

How It Works

When a subscription has statusMappings configured:

1. The platform looks up the original status (e.g., Delivered) in your mapping dictionary
2. If a mapping exists, the mapped value replaces {{Status}} in templates and the default JSON payload
3. If no mapping exists for the status, the original value is used as fallback

Mapping keys are case-insensitive — "sent", "Sent", and "SENT" all match the Sent status.

Example: Map to Your Internal Status Codes

Code
{
  "url": "https://api.yourapp.com/sms-status",
  "httpMethod": "POST",
  "statusMappings": {
    "Sent": "pending",
    "Delivered": "success",
    "Failed": "error"
  }
}

When a message is delivered, the default payload will contain "status": "success" instead of "status": "Delivered". Templates also see the mapped value:

Code
{
  "bodyTemplate": "{\"state\":\"{{Status}}\"}",
  "statusMappings": { "Delivered": "completed" }
}

Produces: {"state":"completed"}

Example: Numeric Status Codes

Code
{
  "statusMappings": {
    "Sent": "1",
    "Delivered": "2",
    "Failed": "-1"
  }
}

Partial Mappings

You don't need to map every status — only the ones you want to rename. Unmapped statuses pass through unchanged:

Code
{
  "statusMappings": {
    "Delivered": "OK",
    "Failed": "ERR"
  }
}

Here, Sent would remain as "Sent" in the payload, while Delivered becomes "OK" and Failed becomes "ERR".

Custom HTTP Methods

By default, webhooks are delivered via POST with a JSON body. You can change this per subscription using the httpMethod field.

Supported Methods

Custom Body Templates

Use bodyTemplate to control the exact JSON (or any text format) sent in the request body for POST, PUT, and PATCH methods.

Example: Custom JSON Structure

Code
{
  "url": "https://api.yourapp.com/sms-callback",
  "httpMethod": "POST",
  "bodyTemplate": "{\"id\":\"{{MessageId}}\",\"state\":\"{{Status}}\",\"to\":\"{{Recipient}}\",\"error\":\"{{FailureReason}}\"}"
}

The platform will deliver:

Code
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "state": "Delivered",
  "to": "+231770001234",
  "error": ""
}

Example: XML Body

Code
{
  "url": "https://api.yourapp.com/sms-xml",
  "httpMethod": "POST",
  "bodyTemplate": "<StatusUpdate><MessageId>{{MessageId}}</MessageId><Status>{{Status}}</Status><Recipient>{{Recipient}}</Recipient></StatusUpdate>"
}

Example: Form-Encoded Body

Code
{
  "url": "https://api.yourapp.com/sms-form",
  "httpMethod": "POST",
  "bodyTemplate": "message_id={{MessageId}}&status={{Status}}&to={{Recipient}}"
}

Custom Query Parameter Templates

Use queryParamTemplate to append query parameters to the webhook URL. This is especially useful for GET requests or when your endpoint expects data in the URL.

Example: GET with Query Parameters

Code
{
  "url": "https://api.yourapp.com/sms-status",
  "httpMethod": "GET",
  "queryParamTemplate": "msg_id={{MessageId}}&status={{Status}}&recipient={{Recipient}}"
}

The platform will call:

Code
GET https://api.yourapp.com/sms-status?msg_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&status=Delivered&recipient=%2B231770001234

Example: POST with Query Params and Body

You can combine both queryParamTemplate and bodyTemplate on body methods:

Code
{
  "url": "https://api.yourapp.com/webhook",
  "httpMethod": "POST",
  "queryParamTemplate": "tenant={{TenantId}}&event=sms_status",
  "bodyTemplate": "{\"id\":\"{{MessageId}}\",\"status\":\"{{Status}}\"}"
}

GET Fallback (No Template)

When httpMethod is GET and no queryParamTemplate is provided, all non-empty variables are automatically appended as query parameters:

Code
GET https://api.yourapp.com/sms-status?messageid=abc123&tenantid=org_1&status=Delivered&senderid=MyApp&recipient=%2B231770001234&timestamp=2026-02-23T14%3A30%3A00.0000000Z&providermessageid=prov-001

Fallback Behavior Summary

Status Values

Webhooks are triggered for the following status transitions:

Failure Scenarios

The Failed status is triggered in these situations:

• Delivery receipt indicates failure — carrier reports the message as failed or expired
• Delivery receipt indicates undelivered — carrier could not deliver the message
• Permanent send failure — the platform exhausted all retry attempts

When a message fails, the failureReason field contains details about why.

Security

HMAC Signature Verification

If you provide a secret when creating a subscription, every webhook delivery includes an X-Hub-Signature-256 header containing an HMAC-SHA256 signature of the payload.

What gets signed:

• For POST/PUT/PATCH: the request body content (either default JSON or interpolated template)
• For GET: the query parameter string

Verification examples (select a language):

Code
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;

public static boolean verifyWebhook(byte[] payload, String signature, String secret) throws Exception {
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    byte[] hash = mac.doFinal(payload);
    String expected = "sha256=" + bytesToHex(hash);
    return MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8),
        signature.getBytes(StandardCharsets.UTF_8));
}

private static String bytesToHex(byte[] bytes) {
    StringBuilder sb = new StringBuilder(bytes.length * 2);
    for (byte b : bytes) {
        sb.append(String.format("%02x", b));
    }
    return sb.toString();
}

Code
using System.Security.Cryptography;
using System.Text;

bool VerifyWebhook(string payload, string signature, string secret)
{
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
    var expected = "sha256=" + Convert.ToHexString(hash).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected),
        Encoding.UTF8.GetBytes(signature));
}

Code
const crypto = require('crypto');

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

Code
import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Code
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

func VerifyWebhook(payload []byte, signature, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(payload)
    expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signature))
}

Code
<?php
function verify_webhook(string $payload, string $signature, string $secret): bool {
    $expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
    return hash_equals($expected, $signature);
}

Timeout

All webhook deliveries have a 5-second timeout. Ensure your endpoint responds promptly. If it times out, the delivery is considered failed (but does not affect SMS processing).

Complete Examples

Example 1: Standard POST Webhook (Default)

Code
{
  "url": "https://api.yourapp.com/sms-status",
  "secret": "whsec_my_secret",
  "name": "Standard Status Hook"
}

Receives the default JSON payload via POST.

Example 2: GET Callback to Legacy System

Code
{
  "url": "https://legacy.yourapp.com/callback",
  "httpMethod": "GET",
  "queryParamTemplate": "id={{MessageId}}&st={{Status}}&phone={{Recipient}}",
  "name": "Legacy System Callback"
}

Calls: GET https://legacy.yourapp.com/callback?id=abc123&st=Delivered&phone=%2B231770001234

Example 3: PUT Upsert with Custom Body

Code
{
  "url": "https://api.yourapp.com/messages/status",
  "httpMethod": "PUT",
  "secret": "whsec_upsert_secret",
  "bodyTemplate": "{\"externalId\":\"{{MessageId}}\",\"deliveryStatus\":\"{{Status}}\",\"updatedAt\":\"{{Timestamp}}\"}",
  "name": "Upsert Delivery Status"
}

Example 4: POST with Query Routing and Minimal Body

Code
{
  "url": "https://api.yourapp.com/events",
  "httpMethod": "POST",
  "queryParamTemplate": "tenant={{TenantId}}&type=sms_status",
  "bodyTemplate": "{\"ref\":\"{{MessageId}}\",\"status\":\"{{Status}}\",\"reason\":\"{{FailureReason}}\"}",
  "name": "Event Router"
}

Example 5: Custom Status Values with Body Template

Code
{
  "url": "https://api.yourapp.com/delivery-status",
  "httpMethod": "POST",
  "secret": "whsec_mapped_secret",
  "bodyTemplate": "{\"messageRef\":\"{{MessageId}}\",\"state\":\"{{Status}}\",\"phone\":\"{{Recipient}}\"}",
  "statusMappings": {
    "Sent": "in_transit",
    "Delivered": "completed",
    "Failed": "rejected"
  },
  "name": "Mapped Status Webhook"
}

When a message is delivered, the webhook sends:

Code
{
  "messageRef": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "state": "completed",
  "phone": "+231770001234"
}