Copy page

Integrations & Identity

Inbound SMS Webhook Specification

Overview

The Inbound SMS Webhook allows you to receive SMS messages sent to your shortcodes in real-time. When a user sends an SMS to your shortcode, the Tech231 Platform will immediately POST the message details to your configured webhook endpoint.

This guide provides the complete specification for implementing and integrating inbound SMS webhooks into your application.

Prerequisites

Before setting up inbound SMS webhooks, you need:

• An active Tech231 Platform account
• An approved shortcode (numeric or shared with keywords)
• A publicly accessible HTTPS endpoint to receive webhooks
• Valid SSL certificate on your webhook endpoint

Webhook Configuration

Setting Up Your Webhook

1. Navigate to your Tech231 Platform dashboard
2. Go to Settings → Webhooks
3. Click "Add Webhook Endpoint"
4. Enter your webhook details:
   • URL: Your HTTPS endpoint (e.g., https://api.yourcompany.com/webhooks/sms)
   • Secret: A secure random string for signature verification
   • Events: Select sms.received
   • Active: Enable the webhook
5. Click "Save" and "Test Webhook" to verify connectivity

Webhook URL Requirements

Your webhook endpoint MUST:

• Use HTTPS (HTTP is not supported)
• Have a valid SSL/TLS certificate
• Respond within 5 seconds
• Return HTTP status codes 200-299 for success
• Be publicly accessible (no localhost or private IPs)

Webhook Payload

Request Format

When an SMS is received, we'll send a POST request to your webhook URL:

Code
POST /webhooks/sms HTTP/1.1
Host: api.yourcompany.com
Content-Type: application/json
X-Tech231-Signature: sha256=a8f3d2c1b4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1
X-Tech231-Event-Id: evt_1234567890abcdef
X-Tech231-Timestamp: 2024-01-15T10:30:00Z
User-Agent: Tech231-Webhook/1.0

{
  "eventType": "sms.received",
  "eventId": "evt_1234567890abcdef",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "messageId": "msg_inbound_abc123xyz",
    "from": "+1234567890",
    "to": "12345",
    "message": "PIZZA Order 2 large pepperoni pizzas",
    "receivedAt": "2024-01-15T10:30:00Z",
    "keyword": "PIZZA",
    "shortcode": "12345",
    "carrier": "T-Mobile",
    "country": "US",
    "encoding": "GSM-7",
    "parts": 1,
    "metadata": {
      "tenantId": "tenant_xyz789",
      "organizationId": "org_abc123"
    }
  }
}

Payload Fields

Root Level

Field	Type	Description
eventType	string	Always "sms.received" for inbound SMS
eventId	string	Unique identifier for this webhook event (for idempotency)
timestamp	string	ISO 8601 timestamp when the event was generated
data	object	The SMS message data (see below)

Data Object

Field	Type	Required	Description
messageId	string	Yes	Unique identifier for the received message
from	string	Yes	Sender's phone number in E.164 format (e.g., +1234567890)
to	string	Yes	Your shortcode that received the message
message	string	Yes	The full text content of the SMS message
receivedAt	string	Yes	ISO 8601 timestamp when the message was received
keyword	string	No	Extracted keyword (first word of message, uppercase)
shortcode	string	Yes	Your shortcode (same as to field)
carrier	string	No	Mobile carrier name (when available)
country	string	Yes	Two-letter ISO country code (e.g., "US", "GB")
encoding	string	Yes	Message encoding: "GSM-7", "UCS-2", or "ASCII"
parts	integer	Yes	Number of SMS parts (1 for standard, >1 for concatenated)
metadata	object	Yes	Additional context information

Metadata Object

Field	Type	Description
tenantId	string	Your tenant identifier
organizationId	string	Your organization identifier in Zitadel

Example Payloads

Simple Inbound SMS

Code
{
  "eventType": "sms.received",
  "eventId": "evt_simple_123",
  "timestamp": "2024-01-15T14:23:45Z",
  "data": {
    "messageId": "msg_inbound_001",
    "from": "+14155551234",
    "to": "54321",
    "message": "HELP I need assistance",
    "receivedAt": "2024-01-15T14:23:45Z",
    "keyword": "HELP",
    "shortcode": "54321",
    "carrier": "AT&T",
    "country": "US",
    "encoding": "GSM-7",
    "parts": 1,
    "metadata": {
      "tenantId": "tenant_abc123",
      "organizationId": "org_xyz789"
    }
  }
}

Multi-Part Inbound SMS

Code
{
  "eventType": "sms.received",
  "eventId": "evt_multipart_456",
  "timestamp": "2024-01-15T14:25:30Z",
  "data": {
    "messageId": "msg_inbound_002",
    "from": "+447911123456",
    "to": "67890",
    "message": "FEEDBACK This is a very long message that exceeds the standard SMS length limit and therefore gets split into multiple parts. The platform automatically reassembles these parts into a single message for your convenience.",
    "receivedAt": "2024-01-15T14:25:30Z",
    "keyword": "FEEDBACK",
    "shortcode": "67890",
    "carrier": "Vodafone",
    "country": "GB",
    "encoding": "GSM-7",
    "parts": 2,
    "metadata": {
      "tenantId": "tenant_abc123",
      "organizationId": "org_xyz789"
    }
  }
}

Unicode/Emoji Message

Code
{
  "eventType": "sms.received",
  "eventId": "evt_unicode_789",
  "timestamp": "2024-01-15T14:30:15Z",
  "data": {
    "messageId": "msg_inbound_003",
    "from": "+33612345678",
    "to": "11111",
    "message": "VOTE 👍 J'aime beaucoup!",
    "receivedAt": "2024-01-15T14:30:15Z",
    "keyword": "VOTE",
    "shortcode": "11111",
    "carrier": "Orange",
    "country": "FR",
    "encoding": "UCS-2",
    "parts": 1,
    "metadata": {
      "tenantId": "tenant_abc123",
      "organizationId": "org_xyz789"
    }
  }
}

Security

Signature Verification

Every webhook request includes an X-Tech231-Signature header containing an HMAC-SHA256 signature. You MUST verify this signature to ensure the request is authentic.

Signature Format

Code
X-Tech231-Signature: sha256=<hex_encoded_signature>

Verification Process

1. Extract the signature from the X-Tech231-Signature header
2. Compute HMAC-SHA256 of the raw request body using your webhook secret
3. Compare the computed signature with the provided signature
4. Use constant-time comparison to prevent timing attacks

Implementation Examples

Node.js:

Code
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  // Remove 'sha256=' prefix if present
  const signatureHash = signature.startsWith('sha256=') 
    ? signature.substring(7) 
    : signature;
  
  // Compute expected signature
  const hmac = crypto.createHmac('sha256', secret);
  const expectedSignature = hmac.update(payload, 'utf8').digest('hex');
  
  // Use timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signatureHash, 'hex'),
      Buffer.from(expectedSignature, 'hex')
    );
  } catch (e) {
    return false;
  }
}

// Usage in Express
app.post('/webhooks/sms', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-tech231-signature'];
  const payload = req.body.toString('utf8');
  
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  // Process the event...
  res.status(200).json({ received: true });
});

Python:

Code
import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    # Remove 'sha256=' prefix if present
    signature_hash = signature[7:] if signature.startswith('sha256=') else signature
    
    # Compute expected signature
    expected_signature = hmac.new(
        secret.encode('utf8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    
    # Use timing-safe comparison
    return hmac.compare_digest(signature_hash, expected_signature)

# Usage in Flask
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/sms', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Tech231-Signature')
    payload = request.get_data()
    
    if not verify_webhook_signature(payload, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401
    
    event = request.get_json()
    # Process the event...
    return jsonify({'received': True}), 200

C# (.NET):

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

public class WebhookVerifier
{
    public static bool VerifySignature(string payload, string signature, string secret)
    {
        // Remove 'sha256=' prefix if present
        var signatureHash = signature.StartsWith("sha256=") 
            ? signature.Substring(7) 
            : signature;
        
        // Compute expected signature
        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
        var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
        var expectedSignature = BitConverter.ToString(hash)
            .Replace("-", "").ToLowerInvariant();
        
        // Use timing-safe comparison
        return CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(signatureHash),
            Encoding.UTF8.GetBytes(expectedSignature)
        );
    }
}

// Usage in ASP.NET Core
[HttpPost("webhooks/sms")]
public async Task<IActionResult> HandleWebhook()
{
    using var reader = new StreamReader(Request.Body);
    var payload = await reader.ReadToEndAsync();
    var signature = Request.Headers["X-Tech231-Signature"].ToString();
    
    if (!WebhookVerifier.VerifySignature(payload, signature, _webhookSecret))
    {
        return Unauthorized("Invalid signature");
    }
    
    var webhookEvent = JsonSerializer.Deserialize<WebhookEvent>(payload);
    // Process the event...
    return Ok(new { received = true });
}

Additional Security Headers

Header	Description
X-Tech231-Event-Id	Unique event identifier for idempotency checking
X-Tech231-Timestamp	Request timestamp for replay attack prevention
User-Agent	Always Tech231-Webhook/1.0

Timestamp Verification:

Reject requests with timestamps older than 5 minutes to prevent replay attacks:

Code
function isTimestampValid(timestamp) {
  const eventTime = new Date(timestamp);
  const now = new Date();
  const fiveMinutes = 5 * 60 * 1000;
  
  return (now - eventTime) < fiveMinutes;
}

Response Handling

Success Response

Return HTTP 200-299 to acknowledge receipt:

Code
HTTP/1.1 200 OK
Content-Type: application/json

{
  "received": true,
  "processedAt": "2024-01-15T10:30:01Z"
}

The response body is optional but recommended for debugging.

Error Responses

If your endpoint returns 4xx or 5xx status codes, we'll retry the webhook.

Client Errors (4xx):

• 400 Bad Request - Malformed request (we won't retry)
• 401 Unauthorized - Invalid signature (we won't retry)
• 404 Not Found - Endpoint not found (we won't retry)
• 429 Too Many Requests - Rate limited (we'll retry with backoff)

Server Errors (5xx):

• 500 Internal Server Error - Server error (we'll retry)
• 503 Service Unavailable - Temporarily unavailable (we'll retry)

Retry Logic

If your endpoint fails, we'll retry with exponential backoff:

Attempt	Delay	Total Time
1st retry	30 seconds	30s
2nd retry	2 minutes	2m 30s
3rd retry	10 minutes	12m 30s
4th retry	30 minutes	42m 30s
5th retry	1 hour	1h 42m 30s

After 5 failed attempts, the webhook is marked as failed and won't be retried. You can view failed webhooks in your dashboard and manually retry them.

Idempotency

Handling Duplicate Events

Due to retries and network issues, you may receive the same event multiple times. Use the eventId field to detect and handle duplicates:

Code
const processedEvents = new Set(); // Or use a database

app.post('/webhooks/sms', async (req, res) => {
  const { eventId, data } = req.body;
  
  // Check if already processed
  if (processedEvents.has(eventId)) {
    console.log(`Event ${eventId} already processed`);
    return res.status(200).json({ received: true, duplicate: true });
  }
  
  // Process the message
  await processInboundSMS(data);
  
  // Mark as processed
  processedEvents.add(eventId);
  
  res.status(200).json({ received: true });
});

Database-Based Idempotency

For production systems, use a database to track processed events:

Code
async function processWebhook(event) {
  const { eventId, data } = event;
  
  // Start transaction
  const transaction = await db.beginTransaction();
  
  try {
    // Check if event already processed
    const existing = await db.webhookEvents.findOne({ 
      eventId 
    }, { transaction });
    
    if (existing) {
      await transaction.commit();
      return { duplicate: true };
    }
    
    // Process the message
    await processInboundSMS(data, transaction);
    
    // Record event as processed
    await db.webhookEvents.create({
      eventId,
      processedAt: new Date(),
      data
    }, { transaction });
    
    await transaction.commit();
    return { success: true };
  } catch (error) {
    await transaction.rollback();
    throw error;
  }
}

Best Practices

Performance

1. Respond quickly: Return 200 OK within 5 seconds
2. Process asynchronously: Queue messages for background processing
3. Use connection pooling: Reuse database connections
4. Implement caching: Cache frequently accessed data

Code
// Good: Quick acknowledgment with async processing
app.post('/webhooks/sms', async (req, res) => {
  const event = req.body;
  
  // Verify signature
  if (!verifySignature(req)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Queue for processing (returns immediately)
  await messageQueue.enqueue(event);
  
  // Respond quickly
  res.status(200).json({ received: true });
  
  // Processing happens in background worker
});

Error Handling

1. Log all errors: Include event ID for debugging
2. Monitor webhook health: Track success/failure rates
3. Set up alerts: Get notified of high failure rates
4. Graceful degradation: Handle missing optional fields

Code
app.post('/webhooks/sms', async (req, res) => {
  try {
    const event = req.body;
    
    // Validate required fields
    if (!event.eventId || !event.data) {
      logger.error('Invalid webhook payload', { event });
      return res.status(400).json({ error: 'Invalid payload' });
    }
    
    // Process with error handling
    await processInboundSMS(event.data);
    
    res.status(200).json({ received: true });
  } catch (error) {
    logger.error('Webhook processing failed', { 
      error: error.message,
      eventId: req.body?.eventId 
    });
    
    // Return 500 to trigger retry
    res.status(500).json({ error: 'Processing failed' });
  }
});

Monitoring

Track these metrics for webhook health:

• Success rate: Percentage of successful webhook deliveries
• Response time: How long your endpoint takes to respond
• Error rate: Percentage of failed webhooks by error type
• Processing latency: Time from message receipt to processing
• Retry rate: How often webhooks are retried

Testing

Local Development

Use tools like ngrok or localtunnel to expose your local server for testing:

Code
# Using ngrok
ngrok http 3000

# Your webhook URL becomes:
https://abc123.ngrok.io/webhooks/sms

Manual Testing

Use the Test Webhook feature in your dashboard:

1. Go to Settings → Webhooks
2. Click "Test" next to your webhook
3. We'll send a sample sms.received event
4. Verify your endpoint receives and processes it correctly

Automated Testing

Mock webhook requests in your test suite:

Code
const request = require('supertest');
const crypto = require('crypto');

describe('SMS Webhook Handler', () => {
  it('should process valid inbound SMS', async () => {
    const payload = {
      eventType: 'sms.received',
      eventId: 'evt_test_123',
      timestamp: new Date().toISOString(),
      data: {
        messageId: 'msg_test_001',
        from: '+1234567890',
        to: '12345',
        message: 'TEST message',
        keyword: 'TEST',
        // ... other fields
      }
    };
    
    const signature = createSignature(
      JSON.stringify(payload),
      WEBHOOK_SECRET
    );
    
    const response = await request(app)
      .post('/webhooks/sms')
      .set('X-Tech231-Signature', `sha256=${signature}`)
      .set('Content-Type', 'application/json')
      .send(payload);
    
    expect(response.status).toBe(200);
    expect(response.body.received).toBe(true);
  });
});

Troubleshooting

Common Issues

Webhook Not Receiving Events

Possible causes:

• Endpoint not publicly accessible
• SSL certificate invalid or expired
• Firewall blocking our IP addresses
• Endpoint returning errors

Solutions:

• Test with curl from an external server
• Verify SSL certificate with SSL Labs
• Whitelist our webhook IPs (contact support)
• Check application logs for errors

Signature Verification Failing

Possible causes:

• Using wrong secret
• Modifying request body before verification
• Character encoding issues
• Incorrect HMAC computation

Solutions:

• Verify secret matches dashboard configuration
• Verify raw body, not parsed JSON
• Use UTF-8 encoding
• Follow implementation examples exactly

Duplicate Events

Possible causes:

• Not implementing idempotency
• Endpoint timing out (slow response)
• Returning error codes unnecessarily

Solutions:

• Track eventId in database
• Respond within 5 seconds
• Return 200 OK even for duplicates

Debug Mode

Enable debug logging in your dashboard to see:

• Raw webhook payloads sent
• Response codes and bodies received
• Retry attempts and timing
• Signature verification details

Support

Need help with webhook implementation?

• 📚 API Reference: Complete webhook API docs
• 💬 Developer Chat: Available in dashboard
• 📧 Email: developers@tech231apps.net
• 🎓 Sample Code: GitHub repository

---

Ready to implement? Configure your webhook endpoint now →