Webhooks Documentation

Real-time notifications for incoming SMS, delivery receipts, and subscription events with HMAC-SHA256 signature verification.

Overview

Webhooks allow you to receive real-time HTTP notifications when events occur on the SMSDESK platform. Instead of polling for updates, the platform will push data to your configured endpoints.

✅ Benefits: Real-time notifications, reduced API calls, event-driven architecture, automatic retries, and secure HMAC-SHA256 signatures.

Webhook Types

The SMSDESK platform supports four types of webhooks:

INCOMING SMS

Purpose: Receive incoming SMS messages

Trigger: SMS received on your channel

Methods: HTTP POST (JSON), HTTP GET, SOAP

Security: HMAC-SHA256 (POST) or Security Key (GET/SOAP)

View Documentation →

DELIVERY REPORTS

Purpose: Track message delivery status

Trigger: Message delivered, failed, or status changed

Methods: HTTP POST (JSON)

Security: HMAC-SHA256

View Documentation →

OPT-OUT / STOP

Purpose: Handle unsubscribe requests

Trigger: Contact sends STOP keyword

Methods: HTTP POST (JSON)

Security: HMAC-SHA256

View Documentation →

OPT-IN / JOIN

Purpose: Handle subscribe requests

Trigger: Contact sends JOIN keyword

Methods: HTTP POST (JSON)

Security: HMAC-SHA256

View Documentation →

Web-Based Subscription Management (NEW)

For Alphanumeric Channels: If your sender ID is alphanumeric (e.g., "SchoolSMS") and cannot receive SMS replies, use our Web-Based Subscription API instead of SMS-based opt-out webhooks.

This allows users to click a link in their SMS to opt-out via a beautiful web page - perfect for channels that can't receive replies.

View Web-Based Subscription API →

Security & Authentication

HMAC-SHA256 Signature

Most webhooks are signed using HMAC-SHA256 to ensure authenticity and prevent tampering.

Signature Process

  1. Take the exact raw JSON body bytes (no normalization or whitespace changes)
  2. Compute HMAC-SHA256(key = sharedSecret, message = rawBodyBytes)
  3. Hex-encode the result in lowercase
  4. Prepend sha256=
  5. Send in the X-Signature header

Example Header

X-Signature: sha256=3a7f2c8d9e1f4b5a6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b
⚠️ Important: The signature must be calculated using the exact bytes sent on the wire. Any re-serialization will result in a different hash.

Configuration

Web Portal Setup

Configure webhooks through your SMSDESK web portal:

  1. Log in to your SMSDESK portal (e.g., https://desk.sms.com.na for Namibia deployment)
  2. Navigate to Account → SMS Channels
  3. Click on your channel to edit
  4. Scroll to the Webhook Settings section
  5. Configure your webhook endpoints and secrets
ℹ️ Note: You can use the "Generate" button next to the secret fields to create cryptographically secure 64-character tokens.

Getting Started

1. Choose Your Webhook Type

Select the webhook type that matches your use case from the cards above.

2. Implement Your Endpoint

Create an HTTP endpoint that can receive POST requests and verify HMAC signatures.

3. Configure in Portal

Add your webhook URL and secret in your SMSDESK web portal.

4. Test & Verify

Send a test message or trigger an event to verify your webhook is working correctly.

Code Examples

We provide code examples in multiple languages:

Ready to Start? Choose a webhook type above and follow the detailed documentation to implement your integration.