Webhooks

Webhooks examples

With a webhook, Voys sends an HTTP request to a URL you provide as soon as someone calls. What happens next is up to you: your server processes the request and sends something back, and the call continues based on that. Think: automatically routing calls based on your own data, looking up the caller's name and showing it on the handset, or just pinging Zapier.

Be sure to check out Call notifications to maximize the capabilities of your telephone service.

Short version: caller calls → Voys sends a request to your URL → your server responds with a status (and optionally some extra data) → Voys continues the call based on that.

Fields in the form

Name — how you'll find it again in your dial plan
Description — just for yourself, doesn't affect anything
Caller ID passthrough — which number the recipient sees: caller's number, dialed number, or suppressed
URL template — the URL that gets called, see below for the variables
Use menu — turn on if the caller needs to enter a code first (IVR-style). Adds 5 extra fields: timeout, number of attempts, start message, error message, timeout message

Variables for your URL template

{code}        the entered code (only relevant if the menu is on)
{did}         the number that was dialed
{callerid}    the caller's number
{callername}  caller's name, if known

Example:

http://webrouting.voys.nl/test.py?code={code}&callerid={callerid}

Voys fills in these four variables automatically before making the request.

Setting it up in your dial plan

Go to Dial plan, pick the number
Click the plus, add a step
Choose Webhook as the type, select your webhook
You automatically get two paths: HTTP and menu succeeded and HTTP or menu failed

In both paths you can use your normal dial plan steps, plus two extra options: variable caller name and variable destination (see below).

What you send back

Your server responds in application/x-www-form-urlencoded format. Required: status. Optional: destination and callername.

Status:

ACK   input/request is valid
NAK   input is invalid
ERR   something went wrong

Just acknowledge:

status=ACK

Route to a different number:

status=ACK&destination=%2B31502102544
status=ACK&destination=215

(destination can be an external number or an internal extension)

Change the caller's name:

status=ACK&callername=VoysPartners

Variable caller name, three flavors

Webhook — takes the name from your server's response
Prepend — adds your text in front of the existing name
Replace — replaces the name entirely with your textI

(Prepend / Replace also work without a webhook, by the way.)

Variable destination

Does your server return a destination? Select "Variable destination" in the routing step and the call automatically goes there.

Examples per use case

1. CRM integration

On an incoming call, Voys sends callerid and did to your CRM. You look up the customer and return the name that should show up on the handset.

URL template:
https://crm.yourcompany.com/webhook?callerid={callerid}&did={did}

Response from your server:
status=ACK&callername=Marieke%20de%20Boer

2. Routing based on an external database

Decide yourself where a call should go, based on the caller, the dialed number, or a pin code.

URL template:
https://routing.yourcompany.com/lookup?callerid={callerid}&did={did}

Response from your server:
status=ACK&destination=%2B31502102544

3. Tracking calls in Google Analytics

Each campaign gets its own number from a block. Voys calls your URL with the campaign (did) and the caller (callerid); you log the conversion, then Voys routes the call on to the real company number. Note: the actual call itself doesn't execute JS, so the tracking has to happen server-side.

URL template:
https://analytics.yourcompany.com/call-tracking?campaign={did}&callerid={callerid}

Response from your server:
status=ACK&destination=020123456

4. Email / Slack on a missed call

Usually via Zapier: your webhook posts to a Zapier catch hook, which forwards it to email, SMS, or Slack.

URL template (Zapier catch hook):
https://hooks.zapier.com/hooks/catch/123456/abcdef?callerid={callerid}&did={did}

What Zapier receives:
{
  "callerid": "+31612345678",
  "did": "0502102544",
  "timestamp": "2026-08-18T09:41:02+02:00"
}

5. VIP pin code

Menu turned on, caller enters a code, you check whether it's valid.

URL template:
https://vip.yourcompany.com/check?code={code}&callerid={callerid}

Valid code:
status=ACK&destination=210

Invalid code:
status=NAK

6. Via Zapier to 300+ apps

Same idea as above, but as a generic trigger. You can pass all four variables and let Zapier decide what to do with them, toward Slack, Gmail, Google Calendar, Zendesk, Mailchimp, Evernote, Dropbox, and so on.

URL template:
https://hooks.zapier.com/hooks/catch/123456/xyz789?callerid={callerid}&did={did}&callername={callername}

What Zapier receives:
{
  "callerid": "+31612345678",
  "did": "0502102544",
  "callername": "Voys Partners"
}