Twilio Integration

Set up HookWatch to receive Twilio webhooks for communication events like incoming SMS messages, voice calls, and delivery status updates.

Prerequisites

A HookWatch account
A Twilio account with a phone number
A server endpoint to process webhook payloads

Step 1: Create a HookWatch endpoint

Go to your Endpoints page
Click "Create Endpoint"
Enter a name like "Twilio Webhooks"
Enter your destination URL (where you want webhooks forwarded)
Copy the generated webhook URL

Your HookWatch URL will look like:

https://hook.hookwatch.dev/wh/abc123xyz

Step 2: Configure Twilio webhooks

For SMS/MMS:

Go to the Twilio Console
Navigate to Phone Numbers > Manage > Active Numbers
Click on the phone number you want to configure
Under "Messaging", set the webhook URL for "A message comes in"
Paste your HookWatch URL and set the method to HTTP POST
Click "Save"

For Voice:

On the same phone number configuration page
Under "Voice", set the webhook URL for "A call comes in"
Paste your HookWatch URL and set the method to HTTP POST
Optionally set a status callback URL for call status updates

Common webhook events:

Incoming SMS/MMS

Message delivered

Message failed

Incoming call

Call completed

Call status update

Recording completed

Transcription ready

Step 3: Verify webhooks on your server

Twilio signs webhook payloads using HMAC-SHA1. HookWatch forwards the X-Twilio-Signature header so you can verify authenticity.

You'll need your Auth Token from the Twilio Console dashboard.

Node.js / Express

Important

Twilio sends webhooks as application/x-www-form-urlencoded, not JSON. Make sure your server parses URL-encoded form data.

Twilio webhook parameters

Twilio sends data as form parameters. Here are the key fields for SMS webhooks:

Parameter	Description
`MessageSid`	Unique identifier for the message
`From`	Sender's phone number
`To`	Recipient's phone number
`Body`	The message text content
`MessageStatus`	Status of the message (queued, sent, delivered, failed)

Testing the integration

Send an SMS to your Twilio phone number from any phone
Make a phone call to your Twilio number
Check your HookWatch Events page to see the events

You can also use the Twilio API to send test messages programmatically.

Common issues

Signature verification fails

The signature is computed using the full webhook URL including the protocol. Make sure the URL in your verification code exactly matches what Twilio has configured.

No TwiML response error

Twilio expects a TwiML XML response for voice webhooks. If your server doesn't respond with valid TwiML, Twilio will play a default error message to the caller.

Status callbacks not arriving

Status callback URLs must be configured separately from the primary webhook URL. Set the status callback URL in the phone number configuration or when making API calls.