Webhooks & Delivery Reports
Receive signed delivery receipts (DLR), opt-out events, and inbound MO messages with X-SmsPro-Signature verification.
SMS Pro posts a signed JSON body to your webhook when a delivery status is ready. Read status on that body.
{
"messageId": "c7a8b9e0-1234-5678-9abc-def012345678",
"providerMessageId": "provider-1001",
"to": "233241234567",
"status": "DELIVERED",
"deliveredAt": "2026-11-18T08:15:04Z",
"gateway": "carrier",
"raw": ""
}Verifying X-SmsPro-Signature
Every outbound webhook includes an X-SmsPro-Signature header signed with your webhook secret (whsec_...):
X-SmsPro-Signature: t=1730462400,v1=5d41402abc4b2a76b9719d911017c592a187383fe52e2e7b57b6f634571999a3Verification requirements:
- Read raw bytes/string: Never re-serialize parsed JSON (
JSON.stringify(req.body)); whitespace or key-order changes break the HMAC digest. - Construct signed string: Concatenate
`${timestamp}.${rawRequestBody}`. - Compute HMAC-SHA256: Hash with your
whsec_...secret as lowercase hex. - Enforce anti-replay window: Reject payloads whose timestamp differs from current Unix time by more than
300seconds (5 minutes). - Constant-time comparison: Compare the hex digests only when they are the same length. Use
crypto.timingSafeEqualin Node.js. In Java, compare equal-length digests withMessageDigest.isEqual.
Step-by-Step Verification Code
Walk through a production-ready Next.js Route Handler verifier in the Verify Delivery Report Webhooks Recipe.
MFA Callback Signatures (X-MFA-Signature)
MFA workflow webhooks (mfa.challenge.created, mfa.challenge.verified, mfa.challenge.test) transmit X-MFA-Signature: sha256=<hex>, computed directly over the raw JSON body with the workflow's webhookSecret.
Endpoint Reliability & Retries
- Respond with any
2xxstatus code within 5 seconds. - Enqueue heavy database or notification side effects asynchronously after signature verification.
- Non-2xx responses or timeouts are retried. Failed deliveries are listed under Developer > Webhooks.
Delivery Reports (DLR) Deep Dive
Architectural mechanics of telecommunication delivery receipts, intermediate vs. terminal states, status mapping, and message correlation.
OTP & Zero-Knowledge MFA
Compare turnkey v1 OTP with v2 Zero-Knowledge SHA-256 Challenge-Response verification and automatic WhatsApp-to-SMS failover.