# Webhooks & Delivery Reports
URL: /docs/guides/webhooks-and-dlr

> 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.

```json title="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` [#verifying-x-smspro-signature]

Every outbound webhook includes an `X-SmsPro-Signature` header signed with your webhook secret (`whsec_...`):

```http
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`.

<Callout type="info" title="Step-by-Step Verification Code">
Walk through a production-ready Next.js Route Handler verifier in the [Verify Delivery Report Webhooks Recipe](/docs/recipes/verify-webhooks).
</Callout>

## MFA Callback Signatures (`X-MFA-Signature`) [#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 [#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**.