🌐 Webhooks

Webhooks offer a powerful mechanism to receive real-time notifications of events like incoming SMS messages. This integration guide will walk you through setting up webhooks to receive such notifications directly from your device.

📩 Supported Events

📦 Batch Webhooks

Batch webhooks deliver multiple messages in a single payload, triggered during inbox refresh operations. They use the same fields as individual events, wrapped in a messages array. Messages are ordered chronologically inside the batch.

Batch webhooks are available for:

Batch Payload Example

{
  "deviceId": "ffffffffceb0b1db0000018e937c815b",
  "event": "sms:batch:received",
  "id": "abc123",
  "webhookId": "xyz789",
  "payload": {
    "messages": [
      {
        "messageId": "a1b2c3",
        "message": "First message",
        "sender": "+1234567890",
        "recipient": "+0987654321",
        "simNumber": 1,
        "receivedAt": "2024-06-22T15:46:11.000+07:00"
      },
      {
        "messageId": "d4e5f6",
        "message": "Second message",
        "sender": "+1234567890",
        "recipient": "+0987654321",
        "simNumber": 1,
        "receivedAt": "2024-06-22T15:47:22.000+07:00"
      }
    ]
  }
}

Prerequisites ✅

Before you begin, ensure the following:

• ⚠️ You have SMS Gateway for Android™ installed on your device in Local, Cloud, or Private mode.
• 🔒 You have a server to receive HTTPS requests:
  • For public servers: Use a valid SSL certificate
  • For private IPs (192.168.x.x, 10.x.x.x): Generate trusted certificates using our Certificate Authority
  • Only http://127.0.0.1 can use HTTP without encryption
• 🌐 Network access:
  • Device must have internet access to reach external endpoints
  • For local networks: Ensure device and server are on same subnet
  • Without internet: See offline webhooks

Step-by-Step Integration 📋

Step 1: Set Up Your Server 🖥️

For your webhooks to work, you need an HTTP server capable of handling HTTPS POST requests. This server will be the endpoint for the incoming webhook data.

• Production: Use a valid SSL certificate.
• Testing: Tools like webhook.site or our Webhook Tester provide temporary endpoints to capture payloads.

Step 2: Register Your Webhook Endpoint 📝

To start receiving webhook notifications, you must register your webhook endpoint with the device. Utilize the curl command to send a POST request to the appropriate address, depending on whether you're in Local, Cloud, or Private mode.

• Local mode:
  • Use the device’s local IP and port (e.g., https://192.168.1.10:8080/webhooks)
  • Only http://127.0.0.1 can use HTTP without encryption
  • For other private IPs: HTTPS with a valid SSL certificate is required
• Private mode: Use your server’s domain name or IP and port (e.g., https://your-server.com/3rdparty/v1/webhooks).
• Cloud mode: Use https://api.sms-gate.app/3rdparty/v1/webhooks.

curl -X POST -u <username>:<password> \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/webhook", "event": "sms:received" }' \
  https://api.sms-gate.app/3rdparty/v1/webhooks

Replace:

• <username>:<password>: Credentials from the Home tab of the app.
• https://your-server.com/webhook: The URL of your webhook endpoint.
• https://api.sms-gate.app/3rdparty/v1/webhooks: The appropriate URL for your mode.

In Cloud and Private modes, please allow some time for the webhooks list to synchronize with your device.

curl -X POST -u <username>:<password> \
-H "Content-Type: application/json" \
-d '{ "url": "https://your-server.com/webhook", "event": "sms:received", "device_id": "DEVICE_ID" }' \
https://api.sms-gate.app/3rdparty/v1/webhooks

Step 3: Verify Your Webhook ✔️

curl -X GET -u <username>:<password> \
  https://api.sms-gate.app/3rdparty/v1/webhooks

Step 4: Test the Webhook 🧪

• sms:received: Send an SMS to the device.
• sms:data-received: Send a data SMS to port 53739.
• mms:received: Send an MMS message to the device.
• mms:downloaded: Wait for the MMS to fully download (fires automatically after mms:received when download completes).
• sms:sent/delivered/failed: Send an SMS or MMS from the app to trigger these events (for MMS, sms:delivered never fires).
• sms:cancelled: Send an SMS or MMS via the cloud/private API, then cancel it via DELETE /3rdparty/v1/messages/{id} while the message is still pending.
• system:ping: Enable the ping feature in the app’s Settings > Ping.
• app:started: Restart the app.

Step 5: Receive the Payload 📤

Your server will receive a POST request with a payload like:

{
  "deviceId": "ffffffffceb0b1db0000018e937c815b",
  "event": "sms:received",
  "id": "Ey6ECgOkVVFjz3CL48B8C",
  "payload": {
    "messageId": "abc123",
    "message": "Android is always a sweet treat!",
    "sender": "6505551212",
    "recipient": "+1234567890",
    "simNumber": 1,
    "receivedAt": "2024-06-22T15:46:11.000+07:00"
  },
  "webhookId": "LreFUt-Z3sSq0JufY9uWB"
}

{
  "deviceId": "ffffffffceb0b1db0000018e937c815b",
  "event": "sms:data-received",
  "id": "Ey6ECgOkVVFjz3CL48B8C",
  "payload": {
    "messageId": "abc123",
    "data": "SGVsbG8gRGF0YSBXb3JsZCE=",
    "sender": "6505551212",
    "recipient": "+1234567890",
    "simNumber": 1,
    "receivedAt": "2024-06-22T15:46:11.000+07:00"
  },
  "webhookId": "LreFUt-Z3sSq0JufY9uWB"
}

{
  "deviceId": "ffffffffceb0b1db0000018e937c815b",
  "event": "mms:received",
  "id": "Ey6ECgOkVVFjz3CL48B8C",
  "payload": {
    "messageId": "mms_12345abcde",
    "sender": "6505551212",
    "recipient": "+1234567890",
    "simNumber": 1,
    "transactionId": "T1234567890ABC",
    "subject": "Photo attachment",
    "size": 125684,
    "contentClass": "IMAGE_BASIC",
    "receivedAt": "2025-08-23T05:15:30.000+07:00"
  },
  "webhookId": "LreFUt-Z3sSq0JufY9uWB"
}

{
  "deviceId": "ffffffffceb0b1db0000018e937c815b",
  "event": "mms:downloaded",
  "id": "Ey6ECgOkVVFjz3CL48B8C",
  "payload": {
    "messageId": "mms_12345abcde",
    "sender": "6505551212",
    "recipient": "+1234567890",
    "simNumber": 1,
    "body": "Hello! Here is the photo.",
    "subject": "Photo attachment",
    "attachments": [
      {
        "partId": 1,
        "contentType": "image/jpeg",
        "name": "photo.jpg",
        "size": 125684,
        "data": "/9j/4AAQ..."
      }
    ],
    "receivedAt": "2025-08-23T05:15:35.000+07:00"
  },
  "webhookId": "LreFUt-Z3sSq0JufY9uWB"
}

{
  "deviceId": "ffffffffceb0b1db0000018e937c815b",
  "event": "sms:sent",
  "id": "Ey6ECgOkVVFjz3CL48B8C",
  "payload": {
    "messageId": "msg-456",
    "sender": "+1234567890",
    "recipient": "+9998887777",
    "simNumber": 1,
    "partsCount": 1,
    "sentAt": "2026-02-18T02:05:00.000+07:00"
  },
  "webhookId": "LreFUt-Z3sSq0JufY9uWB"
}

{
  "deviceId": "ffffffffceb0b1db0000018e937c815b",
  "event": "sms:delivered",
  "id": "Ey6ECgOkVVFjz3CL48B8C",
  "payload": {
    "messageId": "msg-789",
    "sender": "+1234567890",
    "recipient": "+9998887777",
    "simNumber": 1,
    "deliveredAt": "2026-02-18T02:10:00.000+07:00"
  },
  "webhookId": "LreFUt-Z3sSq0JufY9uWB"
}

{
  "deviceId": "ffffffffceb0b1db0000018e937c815b",
  "event": "sms:failed",
  "id": "Ey6ECgOkVVFjz3CL48B8C",
  "payload": {
    "messageId": "msg-000",
    "sender": "+1234567890",
    "recipient": "+4445556666",
    "simNumber": 3,
    "failedAt": "2026-02-18T02:15:00.000+07:00",
    "reason": "Network error"
  },
  "webhookId": "LreFUt-Z3sSq0JufY9uWB"
}

{
  "deviceId": "ffffffffceb0b1db0000018e937c815b",
  "event": "sms:cancelled",
  "id": "Ey6ECgOkVVFjz3CL48B8C",
  "payload": {
    "messageId": "msg-456",
    "sender": "+1234567890",
    "recipient": "+9998887777",
    "simNumber": 1,
    "cancelledAt": "2026-06-22T10:00:00.000+07:00"
  },
  "webhookId": "LreFUt-Z3sSq0JufY9uWB"
}

{
  "deviceId": "ffffffffceb0b1db0000018e937c815b",
  "event": "app:started",
  "id": "Ey6ECgOkVVFjz3CL48B8C",
  "payload": {
    "simCards": [
      {
        "slotIndex": 0,
        "simNumber": 1,
        "phoneNumber": "+79990001234",
        "carrierName": "MTS",
        "iccid": "897010112233445"
      }
    ]
  },
  "webhookId": "LreFUt-Z3sSq0JufY9uWB"
}

Retry Policy

The app implements an exponential backoff retry strategy: it waits 10 seconds before the first retry, then 20 seconds, 40 seconds, and so on, doubling the interval each time. By default, the app will retry 14 times (approximately 2 days) before giving up. You can specify a custom retry count in the app's Settings > Webhooks.

Step 6: Deregister a Webhook 🗑️

If you no longer wish to receive webhook notifications, deregister your webhook with the following curl command:

curl -X DELETE -u <username>:<password> \
  'https://api.sms-gate.app/3rdparty/v1/webhooks/LreFUt-Z3sSq0JufY9uWB'

Webhook Tester 🧪

The Webhook Tester provides a convenient way to inspect webhook requests without setting up your own server. Powered by webhook-tester, it captures incoming HTTP requests and displays them in a web UI for real-time debugging. Available at https://webhook.sms-gate.app for all users.

Quick Start

1. Visit the Webhook Tester URL in your browser
2. A session is automatically created, generating a unique URL like https://webhook.sms-gate.app/550e8400-e29b-41d4-a716-446655440000
3. Register this URL as your webhook endpoint:

curl -X POST -u <username>:<password> \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhook.sms-gate.app/550e8400-e29b-41d4-a716-446655440000",
    "event": "sms:received"
  }' \
  https://api.sms-gate.app/3rdparty/v1/webhooks

Constraints

Local Network Solutions 🏠

For webhooks within private networks:

1. Project CA Certificates
   Generate trusted certificates for private IPs using our Certificate Authority

2. ADB Port Forwarding
   Use 127.0.0.1 with reverse port forwarding:

   adb reverse tcp:9876 tcp:8080
   

   Then register webhook to http://127.0.0.1:9876/webhook

3. Secure Tunnels
   Services like Cloudflare Tunnel or ngrok provide HTTPS endpoints

4. Insecure Build Variant (Not Recommended)
   For local development and testing, use the insecure build variant that allows communication over HTTP without SSL.

Multipart Message Behavior 📨

When sending SMS messages longer than the standard limits (160 characters for GSM‑7 or 70 characters for UCS‑2/Unicode), the app automatically splits the message into multiple parts before transmission. This multipart behavior affects webhook delivery in specific ways:

Security Considerations 🔐

• Review Registered Webhooks Periodically: Regularly audit your webhook URLs to guard against unauthorized or stale endpoints; the app also shows periodic reminders for this review.
• Use HTTPS: Encrypts data in transit.
• Secure Your Endpoint: Protect your webhook endpoint against unauthorized access. Prefer HMAC signature verification (below).
• Rotate Credentials: Regularly update passwords.

Payload Signing 🔏

Webhook requests are signed with HMAC-SHA256 for verification. The device includes these headers:

• X-Signature - Hexadecimal HMAC signature
• X-Timestamp - Unix timestamp (seconds) used in signature generation

The signing key is randomly generated at first request and can be changed in Settings → Webhooks → Signing Key

Verification process:

1. Get raw request body as received (before JSON parsing)
2. Concatenate with X-Timestamp value
3. Compute HMAC-SHA256 using the signing key
4. Compare result with X-Signature header

package webhooks

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

func VerifySignature(secretKey, payload, timestamp, signature string) bool {
  message := payload + timestamp
  mac := hmac.New(sha256.New, []byte(secretKey))
  mac.Write([]byte(message))
  expectedMAC := mac.Sum(nil)
  expectedSignature := hex.EncodeToString(expectedMAC)

  return hmac.Equal([]byte(expectedSignature), []byte(signature))
}

import hmac
import hashlib


def verify_signature(secret_key: str, payload: str, timestamp: str, signature: str) -> bool:
    message = (payload + timestamp).encode()
    expected_signature = hmac.new(secret_key.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected_signature, signature)

const crypto = require('crypto');

function verifySignature(secretKey, payload, timestamp, signature) {
    const message = payload + timestamp;
    const expectedSignature = crypto
        .createHmac('sha256', secretKey)
        .update(message)
        .digest('hex');

    const sig = String(signature).trim().toLowerCase();
    if (sig.length !== expectedSignature.length) return false;
    return crypto.timingSafeEqual(
        Buffer.from(expectedSignature, 'hex'),
        Buffer.from(sig, 'hex')
    );
}

<?php

function verify_signature($secret_key, $payload, $timestamp, $signature) {
    $message = $payload . $timestamp;
    $expected_signature = hash_hmac('sha256', $message, $secret_key);

    return hash_equals($expected_signature, $signature);
}

Inspecting the Delivery Queue 🔍

Pending and failed webhook deliveries are inspectable inside the app, without attaching a debugger or reading logcat:

1. Open app → Settings tab → Webhooks
2. Tap Webhook Queue ("View recent webhook queue entries")

The queue screen lists the most recent entries with filter chips for each state - All, Pending, Processing, Completed, Failed, Permanently Failed - each showing a live count. Filter chips with a count of zero are hidden, so the screen tells you at a glance whether anything is stuck.

Tapping an entry opens its detail view, which shows the target URL, current status, retry count, last error, created and next attempt timestamps, and the exact payload that was queued.

Troubleshooting 🛠️

See Also 📚

• Web Dashboard — graphical webhook management UI
• FAQ
• Status Tracking
• Private Webhook Certificate Setup
• API Documentation

Examples 💡

• Flask webhook processor: Demonstrates registration, HMAC validation, and payload handling with Flask.
• FastAPI webhook processor: Demonstrates registration, HMAC validation, and payload handling with FastAPI.
• Discord Forwarder Function: Forwards SMS to Discord using a cloud function.
• Telegram Forwarder Function: Forwards SMS to Telegram using a cloud function.
• Web Client: Node.js client for sending/receiving SMS via Socket.io.
• Google Sheets - Google Apps Script integration to automatically log incoming SMS messages to Google Sheets.