Skip to content

I Read Twilio's Webhook Docs Three Times Before It Clicked

I Read Twilio's Webhook Docs Three Times Before It Clicked

I read the documentation on webhooks three separate times before it clicked. Not because it was wrong. It was accurate and thorough. It just assumed I already had the idea of "a webhook" in my head. I did not. This is the plain-English version I wish I had found first, plus what to actually do with it on a Twilio or Telnyx number.

A webhook is a forwarding address

Something happens on your phone number: a text arrives, a call comes in, a message you sent is delivered. Your carrier then sends the details of that event to a web address you chose, straight away. Whatever is listening at that address decides what happens next: show the text in an inbox, play a greeting to the caller, mark a message as delivered.

That is all a webhook is. Not a program, not a setting with a dozen options. A forwarding address for events.

The part that took me longest: nothing happens on its own. Buying a number and pointing it nowhere means texts arrive at the carrier and stop there. They are saved in the carrier's message logs, but nothing shows them to your team, nothing replies, and nobody is told.

Webhook or API: which way the call goes

  • An API is something you call. "Send this text." "List my numbers." You ask, it answers.
  • A webhook is something that calls you. "A text just arrived, here it is." You do not ask; it tells you when it happens.

A working business line needs both: the API to send, and webhooks to receive.

The three webhooks a business number needs

WebhookFires whenWhat the listener does
Incoming messageA text or photo arrivesSaves it, shows it to your team, sends alerts, maybe an AI reply
Incoming callSomeone rings the numberAnswers with instructions: forward, phone menu, voicemail, queue
Status callbackA message you sent is delivered or failsMarks it delivered, or explains why the carrier refused it

How a text travels, step by step

  1. A customer sends a text to your business number from their phone.
  2. Their mobile carrier hands it to yours, Twilio or Telnyx, which owns the number on your behalf.
  3. Your carrier saves it in your account's message log. At this point it exists, but nobody has seen it.
  4. Your carrier sends it to your webhook address, signed so the listener can prove it is real.
  5. The listener checks the signature, saves the message, and shows it to your team.
  6. The listener answers your carrier within a few seconds. If it does not, the carrier tries the backup address, if you set one.
  7. When you reply, your app calls the carrier's API to send it, and later a status callback reports whether it was delivered.

Seen that way, every problem has an obvious home. Not arriving at all is step 4. Arriving but not showing is step 5. Sent but never delivered is step 7.

Where you set them in Twilio and Telnyx

Twilio: open the phone number in the Console. Under Messaging there is a field for "A message comes in" and under Voice one for "A call comes in". Each takes a URL. If the number is in a Messaging Service, the service's settings decide where messages go instead.

Telnyx: messages are sent to the webhook URL on the number's messaging profile, and calls follow the number's voice connection or TeXML application.

Both carriers let you add a backup address (Twilio calls it a fallback URL, Telnyx a failover URL) that is used when the main one does not answer. It is worth setting; it is the difference between a short outage and missed customers. Our step-by-step webhook setup guide walks through every screen.

What goes wrong in practice

  1. The listener is down. If the server at your webhook address is offline, inbound texts sit unseen in the carrier logs and calls fail or go to the backup.
  2. The address is wrong. A typo, an old domain, http instead of https. Everything looks set up, nothing arrives.
  3. Messaging Service overrides the number. You set the number's webhook, but the number is in a Messaging Service that points somewhere else. Twilio uses the service.
  4. Nobody checks who is calling. A webhook address is public. Anyone who learns it can send fake "messages" to it unless the listener checks the carrier's signature on each request.
  5. One number at a time. Ten numbers means ten trips through the console, and one is always missed.

A five-point webhook health check

  1. Text your own number. Does it appear where your team works within a few seconds?
  2. Call your own number. Does it ring, play the menu, or reach voicemail as expected?
  3. Send a text out. Does it show as delivered?
  4. Check each number's settings (or its Messaging Service) point at the same, current address, using https.
  5. Check the backup address is set, and points somewhere that is not the same server as the main one.

Do it after any change to your numbers, your domain or your server, and once a month even when nothing has changed.

The security part nobody mentions

Twilio signs every webhook it sends with your account's secret, and Telnyx signs its webhooks with a public key system. A listener that checks those signatures can tell a real carrier event from a fake one sent by anyone who found the address. A listener that does not check will happily show a forged "customer text" in your inbox, or trigger an AI reply that uses your paid credits.

If you build your own listener, verify the signature on every request before doing anything else.

Receiving texts and calls without running a server

If you would rather not host, monitor and secure a listener yourself, a platform can be the listener for you. In TelBuddy:

  • You connect your Twilio or Telnyx account and sync your numbers.
  • Bulk Sync points the SMS and voice webhooks of many numbers at TelBuddy in one go, with a log showing what happened to each number.
  • Every incoming webhook is checked against the carrier's signature, and anything that fails is rejected.
  • Delivery status comes back automatically, so the inbox can show whether each text was delivered and, if not, why in plain English.

See how it works in the Bulk Sync guide, or the wider picture in setting up Twilio or Telnyx without coding.

What actually made it click

Thinking of it as a forwarding address, not a technical configuration, was the whole shift. The carrier forwards events; something has to be at the address to receive them. Once that landed, the documentation went from a wall to a reference. If you are still at the wall, you are in good company, and you are probably closer than you think. For why the raw console is so hard to use as a business tool, see the Twilio Console is not a business phone system.

Frequently asked questions

What is a webhook, in plain English?

A forwarding address for events. When a text or call reaches your number, the carrier sends the details to a web address you chose, and whatever is listening there decides what happens next.

What happens to a text if my webhook is not working?

It still reaches the carrier and is saved in the Twilio or Telnyx message logs, but nothing shows it to your team or acts on it. Setting a backup (fallback or failover) URL helps cover outages.

Is a webhook the same as an API?

No, they go in opposite directions. You call an API to do something, like send a text. A webhook calls you when something happens, like a text arriving.

Do I need my own server to receive texts and calls?

Only if you build it yourself. A platform like TelBuddy is the listener for you, so there is no server to host, monitor or secure.

Are webhook addresses secure?

The address itself is public. Security comes from checking the carrier signature on every request. TelBuddy verifies Twilio and Telnyx signatures and rejects anything that fails.

How do I set webhooks on many numbers at once?

In the carrier consoles it is one number at a time. TelBuddy Bulk Sync sets the SMS and voice webhooks on many numbers in one go, with a log of each result.

TelBuddy Web App in TelBuddy

Run calls and texts on your Twilio or Telnyx account from a web app, without the carrier console.

Joseph Johnson
Founder of TelBuddy. Built it on the Twilio and Telnyx APIs after getting his own number blocked, and went through A2P 10DLC registration the hard way. More about me.