Twilio

Overview

Twilio's signing scheme is unique: the signed string is the full request URL concatenated with all POST parameters (sorted alphabetically by key, with key and value concatenated). This means Splithook must know the exact URL your Twilio account is configured with.

Configure the webhook in Twilio

Set your Splithook endpoint as the webhook URL wherever Twilio calls back — phone number configuration, Studio flows, etc.:

https://splithook.com/e/{slug}

Add the signing secret to Splithook

The signing secret is your Twilio Auth Token, found in the Twilio Console → Account → Auth Token.

1. Settings → Signing secrets → New.
2. Provider: Twilio.
3. Paste your Auth Token.
4. In your destination, set Signing mode to Re-sign, select this secret.

Verify signatures in your handler

Use the official Twilio helper library:

// Node.js
import twilio from 'twilio';

app.post('/webhooks/twilio', (req, res) => {
  const twilioSignature = req.headers['x-twilio-signature'] as string;
  const url = 'https://your-server.com/webhooks/twilio';
  const isValid = twilio.validateRequest(
    process.env.TWILIO_AUTH_TOKEN,
    twilioSignature,
    url,
    req.body
  );
  if (!isValid) return res.status(403).send('Forbidden');
  // handle event...
  res.sendStatus(200);
});

# Python
from twilio.request_validator import RequestValidator
validator = RequestValidator(os.environ['TWILIO_AUTH_TOKEN'])
is_valid = validator.validate(url, request.form, request.headers.get('X-Twilio-Signature'))

How Splithook re-signs Twilio events

Twilio's signature format:

x-twilio-signature: abc123=

Computed as base64(HMAC-SHA1(authToken, url + sorted_params)).

Where sorted_params is all POST parameters sorted by key, with key and value concatenated directly (no separator), then all pairs concatenated.

Example for a request to https://splithook.com/e/ab3dkf7z with body From=+1555...&Body=Hello:

signed_string = "https://splithook.com/e/ab3dkf7z" + "Body" + "Hello" + "From" + "+1555..."

On replay, Splithook reconstructs the signature from the stored URL and parameters. Important: the URL used for signing must match exactly what Twilio has configured — path, query string, everything.

Important: URL must match exactly

When configuring the destination, make sure the destination URL exactly matches the one Twilio will sign against (your local server URL, not the Splithook URL). Splithook uses the destination URL as the base for reconstructing the Twilio signature.