Dots validates webhook signatures to protect your integration from spoofed requests. When Twilio or Plivo sends a webhook to Dots, the signature is checked before any processing occurs. Requests with missing or invalid signatures are rejected with HTTP 401 Unauthorized.
Why Signature Validation Matters
Webhook signature validation prevents attackers from sending fake requests that appear to come from Twilio or Plivo. Without validation, a malicious actor could send forged delivery-status callbacks or verification confirmations, potentially corrupting your SMS delivery logs or bypassing phone verification.
Dots enforces signature validation at the entry point — invalid requests are rejected immediately, before any webhook processing logic runs.
Twilio Webhook Validation
Twilio webhooks sent to Dots must include a valid signature. Dots verifies the signature against the request body and your Twilio credentials before processing the webhook.
What Happens When Validation Fails
If the signature is missing, malformed, or doesn't match the expected value, Dots returns:
HTTP 401 Unauthorized
The webhook processing logic never runs
This ensures that only legitimate Twilio-originated requests affect your SMS delivery status, payout link updates, and verification workflows.
Twilio Webhook Endpoints
POST /api/twilio-webhook — Handles SMS delivery status callbacks
Plivo Webhook Validation
Plivo webhooks undergo signature validation using Plivo's V2 and V3 signature formats. Because Plivo webhooks may arrive through proxies or load balancers, Dots reconstructs the public URL from forwarded headers to validate signatures correctly.
What Happens When Validation Fails
Invalid or unsigned Plivo webhooks are rejected with:
HTTP 401 Unauthorized
No further processing occurs
Plivo Webhook Endpoints
POST /api/plivo-webhook — Handles message delivery status callbacks
POST /api/plivo-verify-webhook — Handles verification session callbacks
Forwarded URL Reconstruction
When Plivo signs webhooks, it uses the public URL that it called. If your webhook URL passes through a proxy, load balancer, or ngrok, the signature validation must use the same public URL to verify correctly. Dots handles this by reconstructing the forwarded public URL from proxy headers before validating the signature.
This validation happens automatically. You don't need to configure anything differently for proxied or forwarded requests.
Testing Webhooks Locally
Webhook signature validation works identically in Sandbox and Production. To test webhooks during local development, use a tunneling service like ngrok to expose your local endpoint to the internet.
If you're integrating with Dots webhooks and receiving 401 errors:
Why am I getting 401 Unauthorized on webhooks?
The most common causes are:
Sending from an untrusted source — Only Twilio or Plivo should send requests to these endpoints. Manually crafted requests without valid provider signatures will be rejected.
URL mismatch (Plivo) — Ensure your Plivo webhook configuration uses the exact public URL that Plivo will call. If you're behind a proxy, the forwarded headers must correctly represent the public URL.
Missing credentials — The provider must have valid credentials configured for signature verification to work.
How does Dots know which URL to use for Plivo signature validation?
Dots uses the X-Forwarded-* headers (Host, Proto, Prefix) to reconstruct the public URL when requests pass through proxies. This ensures signature validation uses the same URL that Plivo used to construct its signature, even when the request was forwarded through infrastructure like load balancers or ngrok.
