Webhooks

Webhooks voorbeelden

Met een webhook stuurt Voys een HTTP-verzoek naar een URL die je opgeeft zodra iemand belt. Wat er daarna gebeurt, bepaal jij: jouw server verwerkt het verzoek en stuurt iets terug, en het gesprek gaat verder op basis daarvan. Denk aan: automatisch gesprekken routeren op basis van je eigen data, de naam van de beller opzoeken en tonen op het toestel, of gewoon Zapier aansturen.

We raden je aan om zeker eens te kijken naar

Gespreksnotificaties om de mogelijkheden van je telefoondienst optimaal te benutten.

Korte versie: beller belt → Voys stuurt een verzoek naar jouw URL → jouw server reageert met een status (en optioneel wat extra data) → Voys vervolgt het gesprek op basis daarvan.

Velden in het formulier

Naam — zo vind je hem terug in je belplan
Omschrijving — enkel voor jezelf, heeft geen invloed op de werking
Caller ID doorgeven — welk nummer de ontvanger ziet: nummer van de beller, gebeld nummer, of onderdrukt
URL-sjabloon — de URL die wordt aangeroepen, zie hieronder voor de variabelen
Menu gebruiken — schakel in als de beller eerst een code moet ingeven (IVR-stijl). Voegt 5 extra velden toe: timeout, aantal pogingen, startbericht, foutmelding, timeout-bericht

Variabelen voor je URL-sjabloon

{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

Voorbeeld:

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

Voys vult deze vier variabelen automatisch in voordat het verzoek wordt verstuurd.

Instellen in je belplan

Ga naar Belplan, kies het nummer
Klik op de plus, voeg een stap toe
Kies Webhook als type, selecteer je webhook
Je krijgt automatisch twee paden: HTTP en menu geslaagd en HTTP of menu mislukt

In beide paden kun je je normale belplan-stappen gebruiken, plus twee extra opties: variabele bellernaam en variabele bestemming (zie hieronder).

Wat je terugzendt

Je server reageert in application/x-www-form-urlencoded formaat. Vereist: status. Optioneel: destination en callername.

Status:

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

Gewoon bevestigen:

status=ACK

Doorverbinden naar een ander nummer:

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

(destination kan een extern nummer of een intern toestel zijn)

De naam van de beller wijzigen:

status=ACK&callername=VoysPartners

Variabele bellernaam, drie varianten

Webhook — neemt de naam uit de respons van je server
Voorvoegsel — voegt jouw tekst toe vóór de bestaande naam
Vervangen — vervangt de naam volledig door jouw tekst

(Voorvoegsel / Vervangen werken trouwens ook zonder webhook.)

Variabele bestemming

Stuurt je server een destination terug? Selecteer "Variabele bestemming" in de routeringsstap en het gesprek gaat daar automatisch naartoe.

Voorbeelden per toepassingsgebied

1. CRM integratie

Bij een inkomende oproep stuurt Voys callerid en did naar je CRM. Je zoekt de klant op en stuurt de naam terug die op het toestel moet verschijnen.

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

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

2. Routeren op basis van een externe database

Bepaal zelf waar een gesprek naartoe moet, op basis van de beller, het gekozen nummer, of een pincode.

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

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

3. Gesprekken volgen in Google Analytics

Elke campagne krijgt een eigen nummer uit een blok. Voys roept jouw URL aan met de campagne (did) en de beller (callerid); je logt de conversie, waarna Voys het gesprek doorstuurt naar het echte bedrijfsnummer. Let op: het gesprek zelf voert geen JS uit, dus de tracking moet server-side gebeuren.

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

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

4. E-mail / Slack bij een gemiste oproep

Meestal via Zapier: je webhook post naar een Zapier catch hook, die het doorstuurt naar e-mail, SMS of 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-pincode

Menu ingeschakeld, beller voert een code in, jij controleert of deze geldig is.

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

Valid code:
status=ACK&destination=210

Invalid code:
status=NAK

6. Via Zapier naar meer dan 300 apps

Zelfde idee als hierboven, maar als een algemene trigger. Je kunt alle vier de variabelen doorgeven en Zapier laten beslissen wat ermee te doen, naar Slack, Gmail, Google Calendar, Zendesk, Mailchimp, Evernote, Dropbox, enzovoort.

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"
}