Skip to content

Provider guide

Twilio webhooks with Hooksmith

To validate a Twilio webhook, build the exact URL Twilio called, append every POST parameter sorted by name as key then value, compute HMAC-SHA1 with your Auth Token, base64 encode it and compare it with X-Twilio-Signature. Hooksmith does this for each request, parses the form body into fields, and forwards a JSON body to your endpoint.

How Twilio signs webhooks

Twilio signs the URL as well as the body, so the check needs the public URL Twilio called.

Header
X-Twilio-Signature.
Algorithm
HMAC-SHA1, base64 encoded, compared in constant time.
What is signed
The full URL, followed by each form parameter as name then value, sorted by name.
Key
Your Twilio Auth Token.
JSON bodies
The URL must carry a bodySHA256 query parameter. Hooksmith checks it against the SHA-256 of the body, then signs the URL alone.
Replay window
None. The signature has no timestamp, so there is no tolerance setting.
  • Hooksmith builds the URL from the request, applying x-forwarded-host and x-forwarded-proto when a proxy sits in front. If the public URL still differs, set source.verification.url to the exact URL Twilio calls.
  • It tries the URL both with and without its default port.
  • A second request with the same I-Twilio-Idempotency-Token within 24 hours is reported as a duplicate and is not delivered again. To deliver an event Hooksmith already accepted again, use hooksmith replay <event-id>, which skips the duplicate check.

Set it up

Hooksmith turns the provider preset into a hook you own. The signing secret exists before the endpoint does, so store it first, then deploy, then enter the URL in the provider dashboard. Secrets live in your workspace vault and never go in the YAML. Store TWILIO_AUTH_TOKEN, DESTINATION_URL.

  1. In the Twilio Console, open the phone number (or Messaging Service) that receives messages.
  2. Set its incoming message webhook to the /h/<id> URL that hooksmith deploy printed, with method HTTP POST. Voice and status callbacks take a URL the same way.
  3. Store your Auth Token as TWILIO_AUTH_TOKEN. It is shown in the Console under account info.
terminal
hooksmith login
hooksmith new twilio-inbound-sms --preset twilio --yes
# paste the example hook into .hooksmith/hooks/twilio-inbound-sms.yaml
hooksmith secrets set TWILIO_AUTH_TOKEN
hooksmith secrets set DESTINATION_URL
hooksmith test twilio-inbound-sms --payload ./sms.json
hooksmith deploy twilio-inbound-sms   # prints the /h/<id> URL

hooksmith new writes the preset's starter hook. Replace its contents with the example below, or edit it by hand. The CLI's built-in test sample is generic, so pass your own payload with --payload; a matching one is in the next section. The command reference is in the docs.

Forward inbound SMS and ignore status callbacks

Twilio posts form fields such as From, To and Body. Hooksmith turns them into a JSON object before the template runs. This hook skips requests with no Body, which is how status callbacks look, and forwards the rest as JSON.

.hooksmith/hooks/twilio-inbound-sms.yaml
apiVersion: hooksmith/v1
kind: Hook
metadata:
  name: twilio-inbound-sms
  description: Inbound SMS to the support inbox
spec:
  source:
    preset: twilio
  destinations:
    - name: inbox
      url: ${DESTINATION_URL}
      method: POST
      timeout: 8s
      retries:
        max: 3
        backoff: exponential
        initialDelay: 500ms
  transform:
    engine: handlebars
    fields:
      message_sid: "{{{MessageSid}}}"
      from: "{{{From}}}"
      to: "{{{To}}}"
      text: "{{{Body}}}"
  conditions:
    - if: "!Body"
      then:
        skip: true
  variables:
    - name: TWILIO_AUTH_TOKEN
      from: secret
    - name: DESTINATION_URL
      from: secret
sms.json
{
  "MessageSid": "SM2xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "From": "+15551234567",
  "To": "+18005551212",
  "Body": "Is my order ready?"
}
  • DESTINATION_URL is a workspace secret, so the URL stays out of the YAML. Store it with hooksmith secrets set DESTINATION_URL.
  • Values use triple braces so quotes, ampersands, apostrophes and equals signs reach your endpoint as typed. With double braces, template output is HTML-escaped.
  • Hooksmith replies to Twilio with JSON, not TwiML. Use it to forward and record events. If Twilio must receive TwiML to reply to the sender or control a call, that response has to come from your own endpoint.

What Twilio sends to a webhook

Twilio does not name events. The kind of webhook depends on where you set the URL, and the fields in the request tell them apart.

Incoming message
Form fields include MessageSid, From, To and Body.
Message status callback
MessageStatus such as queued, sent, delivered, undelivered or failed.
Incoming call
Form fields include CallSid, From and To.
Call status callback
CallStatus such as ringing, in-progress, completed, busy, no-answer, failed or canceled.

Test against localhost

The Hooksmith desktop app for Mac can tunnel stored events to a server on your machine. In raw mode it replays the original body bytes and the stored provider headers. Proxy headers such as x-forwarded-host are never stored, so they are not replayed. The target must be localhost, 127.0.0.1, [::1] or a *.localhost name. Get it on the download page.

Twilio signed the public Hooksmith /h/<id> URL, not your localhost URL, so give your local validator that public URL to check against.

Questions

How does Twilio signature validation work?

Twilio takes the full URL of your webhook, appends each POST parameter as name then value in alphabetical order, computes HMAC-SHA1 with your Auth Token and sends the base64 result in X-Twilio-Signature. Hooksmith rebuilds the same string and compares it in constant time. Because the URL is part of the signature, the URL must match exactly.

Why does Twilio signature validation fail behind a proxy?

The signed URL is the one Twilio called, and a proxy can change the host or scheme the server sees. Hooksmith applies x-forwarded-host and x-forwarded-proto when present. If that is still not the public URL, set source.verification.url on the hook to the exact URL configured in Twilio, including any query string.

Does Hooksmith support Twilio JSON webhooks?

Yes, when the URL carries the bodySHA256 query parameter that Twilio adds to JSON webhooks. Hooksmith compares it with the SHA-256 of the body and then validates the signature over the URL. A JSON request without that parameter is rejected.

Can I use the desktop tunnel for Twilio webhooks?

The tunnel replays the stored body and the X-Twilio-Signature header to localhost. But Twilio signed the public Hooksmith /h/<id> URL, not your localhost URL, so a local validator must be given that public URL to check against.

Can Hooksmith reply to a Twilio message with TwiML?

No. Hooksmith acknowledges every accepted request with a JSON 200 response. It suits forwarding, alerting and logging of Twilio events, not flows where Twilio waits for TwiML in the response.

Other providers

All providers are listed on webhook providers. Hooks are metered by events processed: see pricing.