smsriver.com
Get API Key

Webhook HMAC Signature Verification & Security | SMSRiver

Executable code examples in Python, Node.js, and Go for validating inbound SMS webhook signatures against Twilio, Telnyx, and SMSRiver specs.

verify_signature.py
HMAC-SHA256 Security 
import hmac, hashlib

def verify_smsriver_signature(secret: str, signature: str, raw_body: bytes) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)
verify_signature.ts
REST API v1 
import crypto from "crypto";

export function verifySignature(secret: string, signature: string, rawBody: Buffer): boolean {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Language & Runtime Performance Benchmarks

Runtime / Framework E2E Latency Memory Footprint Concurrency Model
HMAC-SHA256 Node Crypto 0.4ms median 8 MB RSS V8 C++ native cryptographic binding
HMAC-SHA256 Python hashlib 0.6ms median 12 MB RSS CPython OpenSSL cryptographic wrapper
Cloudflare SubtleCrypto 0.2ms median 4 MB RSS WebAssembly / V8 native isolate primitive
OpenSSL CLI Verification 3.5ms median 6 MB RSS Single process fork execution

Implementation Walkthrough

1

Capture Raw Request Body

Ensure your web framework does not parse or modify the raw bytes before computing the cryptographic hash.

2

Extract Signature Header

Retrieve the `X-SMSRiver-Signature` or `X-Twilio-Signature` header from the incoming HTTP request.

3

Constant-Time Comparison

Always use `hmac.compare_digest` or `crypto.timingSafeEqual` to prevent timing attacks.

Supported MCP Agent Tools

list_countries
alias: sms_list_numbers

Discover supported countries, inventory counts, and carrier capabilities by source type.

get_number_capabilities
alias: sms_get_capabilities

Check line types, SMS capabilities, carrier limitations, and rental costs for a phone number or ISO country.

create_test_inbox
alias: sms_create_inbox

Create an isolated synthetic test inbox for deterministic webhook integration testing without real carriers.

generate_test_sms
aliases: sms_generate_sms, sms_create_synthetic_message

Inject zero-carrier-cost synthetic SMS inbound events directly into webhook endpoints for CI/CD test automation.

simulate_delivery_failure
alias: sms_simulate_failure

Simulate carrier drops, 10DLC rejections, DND blocks, and queue timeouts to verify retry handling.

inspect_webhook_events
alias: sms_inspect_webhooks

Query recorded test events, delivery status, latency, and raw carrier webhook payloads within plan retention.

replay_test_event
alias: sms_replay_event

Replay an existing test event to re-trigger local webhooks or reproduce failed integration test cases.

get_usage_summary
alias: sms_get_usage

Inspect current billing plan, monthly quota, consumed requests, and remaining units across REST and MCP.

Engineering Architecture Spec
Read Full MCP Guide

Building an SMS Model Context Protocol (MCP) Server for Autonomous AI Agents

Learn how autonomous agents execute JSON-RPC 2.0 stdio tools, extract multi-factor verification codes using deterministic regex tokenizers, and execute end-to-end authentication in Claude Desktop and Cursor IDE.

Frequently Asked Questions • Developer & MCP Integration

How do I configure the SMSRiver Model Context Protocol (MCP) server?

Add SMSRiver to your AI assistant configuration (such as claude_desktop_config.json) using standard stdio or SSE transports pointing to the SMSRiver MCP gateway. You can immediately inspect available test inboxes and trigger simulated SMS deliveries.

Can I test inbound webhooks locally without incurring carrier fees?

Yes. SMSRiver's synthetic testing API allows you to inject mock SMS events into your local or staging webhook handlers with zero telecom carrier fees and sub-millisecond response times.

Does SMSRiver support automated webhook payload replay?

Yes. Inbound webhook payloads captured during test runs can be replayed on-demand via the REST API to reproduce edge cases, inspect parser failures, and verify signature validation routines.

Related Developer Tools, Guides & Country Line Pools

Telecom & Payload Utilities

Telecom Protocol Specs

Live Country Inboxes for Testing

Copied to clipboard