Skip to Content

Webhooks & Delivery Reports

Receive signed delivery receipts (DLR), opt-out events, and inbound MO messages with X-SmsPro-Signature verification.

View Markdown (.md)

SMS Pro posts a signed JSON body to your webhook when a delivery status is ready. Read status on that body.

Delivery status 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=5d41402abc4b2a76b9719d911017c592a187383fe52e2e7b57b6f634571999a3

Verification requirements:

  1. Read raw bytes/string: Never re-serialize parsed JSON (JSON.stringify(req.body)); whitespace or key-order changes break the HMAC digest.
  2. Construct signed string: Concatenate `${timestamp}.${rawRequestBody}`.
  3. Compute HMAC-SHA256: Hash with your whsec_... secret as lowercase hex.
  4. Enforce anti-replay window: Reject payloads whose timestamp differs from current Unix time by more than 300 seconds (5 minutes).
  5. Constant-time comparison: Compare the hex digests only when they are the same length. Use crypto.timingSafeEqual in Node.js. In Java, compare equal-length digests with MessageDigest.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 2xx status 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.

On this page