Inkomende webhook (vóór het gesprek)

Met de inkomende webhook roepen wij je server aan zodra een oproep binnenkomt, nog vóór de begroeting. De JSON die je terugstuurt gebruikt de assistent tijdens dat gesprek, bijvoorbeeld om de beller met naam te begroeten of een openstaande factuur te noemen.

Wanneer wordt hij aangeroepen?

• Inkomende telefoongesprekken: bij elke oproep die de assistent aanneemt, vóór de begroeting, ook voor onbekende nummers. De beller wacht tot je server heeft geantwoord.
• Sms, WhatsApp en webchat: niet.
• Uitgaande gesprekken: niet. Daar geef je zelf variabelen mee via de campagne of de API; zie Uitgaande gesprekken.
• Uitproberen: niet. Test de webhook dus met een echte oproep.

Een oproep die wordt geweigerd, bijvoorbeeld van een geblokkeerd contact, roept de webhook niet aan. Een voorwaarde op de actie heeft hier geen effect: staat de actie aan, dan loopt hij bij elke oproep op die assistent.

Het verzoek

Met een leeg Body-sjabloon sturen wij een POST met deze JSON-body en de header X-Yarla-Signature (zie Webhooks voor het controleren van de handtekening). De punt staat letterlijk in de veldnaam.

{
  "fromNumber": "+31612345678",
  "toNumber": "+31201234567",
  "personNumber": "+31612345678",
  "agentNumber": "+31201234567",
  "company.name": "Loodgieter Jansen",
  "company.website": "https://www.voorbeeld.nl",
  "company.phone": "+31201234567",
  "company.email": "info@voorbeeld.nl",
  "company.address": ""
}

Veld	Betekenis
personNumber, fromNumber	Nummer van de beller (E.164). Beide velden hebben dezelfde waarde.
agentNumber, toNumber	Je nummer dat gebeld is. Beide velden hebben dezelfde waarde.
company.name	De naam van je bedrijf.
company.website, company.phone, company.email	Je website en het telefoonnummer en e-mailadres voor klanten. Leeg als je ze niet hebt ingevuld.
company.address	Je adres, alleen als Adres delen met klanten aan staat. Anders leeg.

Andere gegevens, zoals het id van het gesprek of het kanaal, gaan niet mee. In een eigen Body-sjabloon kun je alleen deze velden gebruiken, bijvoorbeeld {{personNumber}} of {{company.name}}; andere variabelen zoals {{conversationId}} blijven leeg. Een GET-verzoek heeft geen body en wordt niet ondertekend, dus laat de methode liever op POST.

De Authorization-sleutel van de actie wordt bij dit verzoek niet meegestuurd. Verwacht je endpoint een sleutel, zet die dan bij Headers, bijvoorbeeld X-Api-Key: …. Die waarde staat leesbaar in het formulier.

Het antwoord

Antwoord met een 2xx-status, bijvoorbeeld 200, en een JSON-object, het liefst plat: sleutels met strings, getallen of booleans.

{
  "customerName": "Jan de Vries",
  "customerId": "C-1042",
  "openInvoice": true,
  "lastVisit": "2026-06-12"
}

Regels:

• Een leeg object {}, een status buiten 2xx, een antwoord dat geen JSON-object is (zoals een lijst of gewone tekst) of een time-out (3 seconden) betekent geen context. De assistent begint dan gewoon zonder; het gesprek gaat altijd door. Een mislukt verzoek wordt niet opnieuw geprobeerd.
• Geneste objecten blijven genest: { "customer": { "name": "Jan" } } gebruik je als {{customer.name}}.
• Gebruik geen lijsten. Zet een lijst zelf om naar een leesbare tekst, bijvoorbeeld "openInvoices": "2 facturen, totaal € 340".
• Houd het klein: een handvol velden. Alles wat je teruggeeft wordt onderdeel van de prompt. Een antwoord langer dan 20.000 tekens wordt afgekapt en daardoor niet meer gelezen.
• Heb je meerdere acties vóór het gesprek, dan lopen ze na elkaar en worden hun antwoorden samengevoegd. Bij dezelfde veldnaam geldt het laatste antwoord. Elke actie krijgt 3 seconden, dus de beller wacht langer.

De context gebruiken

In de begroeting. Daar zijn de velden direct beschikbaar onder hun eigen naam, bijvoorbeeld {{customerName}}. De langere vorm {{inboundContext.customerName}} blijft daar leeg.

In de prompt. De assistent krijgt alle velden tijdens het gesprek vanzelf als context mee. Als variabele werken ze in de prompt niet: {{customerName}} blijft daar leeg. Noem het veld daarom gewoon bij naam, zoals in het voorbeeld onder Instellen.

In acties tijdens het gesprek. Een HTTP-verzoek of Google Sheets-actie tijdens het gesprek kan deze velden niet als variabele gebruiken. Heb je zo'n waarde daar nodig, maak er dan een parameter van bij Parameters die de assistent invult.

In acties na het gesprek. In e-mail, sms, HTTP-verzoek en Google Sheets gebruik je altijd de vorm {{inboundContext.customerName}}. In de standaardbody van de webhook na het gesprek staan alle velden onder inboundContext.

In de Inbox. Bij het gesprek zie je de teruggegeven velden onder Technische details, bij Gegevens die voor het gesprek zijn opgezocht, zodat je kunt controleren wat de assistent wist. Een mislukt verzoek zie je daar alleen als {}: Wat de acties hebben gedaan toont alleen acties na het gesprek.

Ontbreekt een veld, dan is de variabele leeg. Omdat de begroeting vaste tekst is, leest "Goedemiddag, {{customerName}}" vreemd als er geen naam is. Laat het gebruik van de naam daarom liever over aan een regel in de prompt.

Instellen

1. Open de assistent onder Assistenten, ga naar het tabblad Taken, open de kaart Acties en klik op Nieuw toevoegen. Daarvoor heb je de rol Bewerker of Beheerder nodig.
2. Kies HTTP-verzoek.
3. Geef de actie een Naam en kies bij Wanneer de optie Vóór het gesprek.
4. Vul bij URL het adres van je endpoint in, bij voorkeur met https://. Interne en privé-adressen worden geweigerd. Laat de Methode op POST en het Body-sjabloon leeg om het standaardverzoek van hierboven te versturen.
5. De actie wordt automatisch opgeslagen zodra hij een naam en een geldig webadres heeft. Klik daarna op Sluiten.
6. Bel het nummer van de assistent en controleer in de Inbox of Technische details de verwachte velden toont.

Voeg daarna op het tabblad Instructies een regel toe bij Belangrijke regels (in Geavanceerde modus: bij Volledige prompt), bijvoorbeeld:

Als customerName bekend is, spreek de beller met naam aan en vraag of het om het bekende adres gaat.
Als customerName leeg is of ontbreekt, vraag dan eerst naar de naam.
Als openInvoice waar is, wijs vriendelijk op de openstaande factuur voordat je een nieuwe afspraak inplant.

Tips

• Antwoord binnen 3 seconden. Zoek op telefoonnummer met een index of cache, en doe niet meer dan één opzoekactie per verzoek.
• Onbekend nummer? Geef {} terug met status 200. Een foutstatus heeft hetzelfde effect.
• Geef nooit geheimen of gevoelige gegevens terug zoals wachtwoorden, IBAN of BSN. Alles wat je teruggeeft komt in de prompt en is zichtbaar in de Inbox en via de API.
• Normaliseer het nummer aan je kant: personNumber staat in E.164 (+31612345678), je CRM misschien niet. Bij een afgeschermd nummer kan het veld leeg zijn of geen telefoonnummer bevatten.
• Geen eigen server? Met Make of n8n zoek je zonder code een contact op in HubSpot of Google Sheets en geef je het antwoord terug; zie Make en n8n.

Gerelateerde artikelen

• HTTP-verzoek
• Een goede prompt schrijven
• Make en n8n
• Webhooks