# Webhooks
Twilio sends webhook requests to your application when events happen — calls
connect, messages are received, status changes occur, etc. This guide covers
verifying and handling those requests.
## Signature Verification
Every webhook request includes an `X-Twilio-Signature` header. Always verify
it before trusting the payload to prevent spoofed requests.
### Form-Encoded Webhooks
Most Twilio webhooks send form-encoded POST bodies:
```elixir
url = "https://myapp.com/twilio/voice"
params = conn.params # %{"CallSid" => "CA123", "From" => "+14158675310", ...}
signature = get_req_header(conn, "x-twilio-signature") |> List.first()
auth_token = Application.fetch_env!(:twilio_elixir, :auth_token)
if Twilio.Webhook.valid?(url, params, signature, auth_token) do
handle_call(params)
else
send_resp(conn, 403, "Invalid signature")
end
```
### JSON Body Webhooks
Some newer Twilio webhooks send JSON bodies. These use a different
verification method — a SHA256 hash of the body is appended to the URL:
```elixir
url = "https://myapp.com/twilio/status"
body = conn.assigns.raw_body # the raw request body string
signature = get_req_header(conn, "x-twilio-signature") |> List.first()
auth_token = Application.fetch_env!(:twilio_elixir, :auth_token)
if Twilio.Webhook.valid_body?(url, body, signature, auth_token) do
event = JSON.decode!(body)
handle_event(event)
else
send_resp(conn, 403, "Invalid signature")
end
```
## How Verification Works
Twilio's signature algorithm:
1. Take the full webhook URL (including scheme, host, port, and path)
2. For form-encoded bodies: sort the POST parameters alphabetically by key,
then append each key-value pair to the URL
3. For JSON bodies: compute the SHA256 hash of the raw body, append it to the
URL as `?bodySHA256=<hash>`
4. HMAC-SHA1 the resulting string using your Auth Token as the key
5. Base64-encode the result
The `X-Twilio-Signature` header contains this Base64-encoded HMAC. The SDK
uses constant-time comparison to prevent timing attacks.
## Phoenix Integration
### Basic Controller
```elixir
defmodule MyAppWeb.TwilioController do
use MyAppWeb, :controller
@auth_token Application.compile_env!(:twilio_elixir, :auth_token)
def voice(conn, params) do
url = current_url(conn)
signature = get_req_header(conn, "x-twilio-signature") |> List.first()
if Twilio.Webhook.valid?(url, params, signature, @auth_token) do
xml = Twilio.TwiML.VoiceResponse.new()
|> Twilio.TwiML.VoiceResponse.say("Hello! Thanks for calling.")
|> Twilio.TwiML.VoiceResponse.to_xml()
conn
|> put_resp_content_type("text/xml")
|> send_resp(200, xml)
else
send_resp(conn, 403, "Forbidden")
end
end
def message(conn, params) do
url = current_url(conn)
signature = get_req_header(conn, "x-twilio-signature") |> List.first()
if Twilio.Webhook.valid?(url, params, signature, @auth_token) do
from = params["From"]
body = params["Body"]
Logger.info("SMS from #{from}: #{body}")
xml = Twilio.TwiML.MessagingResponse.new()
|> Twilio.TwiML.MessagingResponse.message("Thanks for your message!")
|> Twilio.TwiML.MessagingResponse.to_xml()
conn
|> put_resp_content_type("text/xml")
|> send_resp(200, xml)
else
send_resp(conn, 403, "Forbidden")
end
end
defp current_url(conn) do
MyAppWeb.Endpoint.url() <> conn.request_path
end
end
```
### Router
```elixir
# lib/my_app_web/router.ex
scope "/twilio" do
post "/voice", MyAppWeb.TwilioController, :voice
post "/message", MyAppWeb.TwilioController, :message
end
```
## URL Considerations
The URL used for verification **must exactly match** the URL Twilio sends
the request to, including:
- **Scheme** (`https://` not `http://`)
- **Host** (the public-facing hostname, not `localhost`)
- **Port** (include non-standard ports like `:8443`)
- **Path** (exact match, including trailing slashes)
If you're behind a reverse proxy or load balancer, make sure you reconstruct
the URL from the original request, not the proxied one. Using your
endpoint's configured URL (as shown above) is usually the safest approach.
## Status Callbacks
When you create a call or message, you can specify a `StatusCallback` URL.
Twilio will send webhooks as the resource's status changes:
```elixir
{:ok, message} = Twilio.Api.V2010.MessageService.create(client, %{
"To" => "+15551234567",
"From" => "+15559876543",
"Body" => "Hello!",
"StatusCallback" => "https://myapp.com/twilio/status"
})
```
Status callback webhooks are verified the same way as other webhooks — check
the `X-Twilio-Signature` header.
## Common Webhook Parameters
### Voice Webhooks
| Parameter | Description |
|-----------|-------------|
| `CallSid` | Unique identifier for the call |
| `From` | Caller's phone number |
| `To` | Called phone number |
| `CallStatus` | `ringing`, `in-progress`, `completed`, `busy`, `no-answer`, `failed` |
| `Direction` | `inbound` or `outbound-api` |
### Messaging Webhooks
| Parameter | Description |
|-----------|-------------|
| `MessageSid` | Unique identifier for the message |
| `From` | Sender's phone number |
| `To` | Recipient's phone number |
| `Body` | Message text |
| `NumMedia` | Number of media attachments |
| `MediaUrl0` | URL of the first media attachment |
## Tips
- **Always verify signatures.** Never trust webhook data without checking
`X-Twilio-Signature`.
- **Respond quickly.** Twilio expects a response within 15 seconds for voice
webhooks or the call will fail. Process events asynchronously if needed.
- **Return TwiML.** Voice and messaging webhooks expect an XML response.
See the [TwiML guide](twiml.md) for building responses.
- **Handle duplicates.** Network retries can cause the same webhook to arrive
more than once. Use `CallSid` or `MessageSid` as an idempotency key.
- **Use HTTPS.** Twilio will only send webhooks to HTTPS URLs in production.
For local development, use [ngrok](https://ngrok.com) or similar.
