Problemen oplossen: webhooks
Webhooks koppelen Yarla aan je eigen systemen: vóór het gesprek (context ophalen), tijdens het gesprek (tools) en na het gesprek (resultaten doorsturen). Je maakt ze als actie HTTP-verzoek onder Assistenten → Taken, op de kaart Acties.
Gaat er iets mis na het gesprek, dan zie je dat het snelst in de Inbox: open het gesprek, klap Technische details open en kijk onder Wat de acties hebben gedaan. Daar staan per actie de naam en de uitkomst, bijvoorbeeld HTTP 200 of HTTP 500 met het begin van je antwoord. Het verzoek zelf en de duur worden niet bewaard. Acties vóór en tijdens het gesprek staan hier niet bij; kijk daarvoor in de logs van je endpoint. Hieronder de meest voorkomende problemen.
Symptomen, oorzaken en oplossingen
| Symptoom | Waarschijnlijke oorzaak | Oplossing |
|---|---|---|
| Je endpoint geeft 401 (handtekening ongeldig) | Verkeerd (vervangen) geheim, body aangepast vóór verificatie, of tijdsverschil | Gebruik de ruwe body, het huidige geheim en sta 300 s verschil toe |
| Context vóór het gesprek ontbreekt | Geen inkomend telefoongesprek, antwoord te traag (langer dan 3 s), geen 2xx, geen JSON-object | Antwoord binnen 3 s met een 2xx-status en een JSON-object |
| Geen aanroep ontvangen op je endpoint | Actie uit of niet op deze assistent, voorwaarde niet vervuld, typfout in URL, endpoint niet publiek, of Uitproberen zonder Acties echt uitvoeren | Controleer Wat de acties hebben gedaan in de Inbox |
| Antwoord van de tool wordt niet gebruikt | Toelichting op het antwoord ontbreekt, antwoord te groot of geen 2xx | Zie Problemen oplossen: prompt en tools |
| Webhook na het gesprek komt twee keer binnen | Twee acties met dezelfde URL, of een proxy of tunnel herhaalt het verzoek | Verwijder de dubbele actie en dedupliceer op conversationId |
| Time-out | Endpoint reageert trager dan 3 s (vóór), 6 s (tijdens) of 8 s (na het gesprek) | Antwoord na het gesprek eerst met 2xx en verwerk asynchroon |
| Variabelen leeg in de body | Variabele niet gedefinieerd, niet genoemd in het gesprek of op dat moment niet beschikbaar | Definieer de variabele op de actie of gebruik een parameter |
| Make of n8n ontvangt niets | Scenario niet actief of webhook-URL veranderd | Activeer het scenario en werk de URL bij |
Header X-Yarla-Signature ontbreekt | De actie gebruikt de methode GET | Gebruik POST, PUT, PATCH of DELETE |
Je endpoint geeft 401 omdat de handtekening niet klopt
Elke aanroep behalve GET draagt de header X-Yarla-Signature: t=<unix seconds>,v1=<hex hmac_sha256(secret, t + "." + body)>. Een mismatch heeft bijna altijd een van drie oorzaken.
- Verkeerd geheim. Heb je onder Instellingen → Koppelingen, op de kaart Webhookgeheim, op Nieuwe maken geklikt, dan werkt het oude geheim direct niet meer en moet je endpoint het nieuwe gebruiken. Alleen een Beheerder ziet die kaart.
- Aangepaste body. Bereken de HMAC over de ruwe bytes van de body zoals ontvangen; een geparste en opnieuw geserialiseerde JSON geeft een andere hash.
- Tijdsverschil. Vergelijk
tmet je eigen klok en sta een verschil van 300 seconden toe.
Zie Webhooks.
Context vóór het gesprek ontbreekt
De inkomende webhook is een HTTP-verzoek met Vóór het gesprek als moment. Ze loopt alleen bij inkomende telefoongesprekken, dus niet bij uitgaande gesprekken, sms, WhatsApp, webchat of Uitproberen. Je endpoint moet binnen 3 seconden antwoorden met een 2xx-status en een JSON-object. Is het antwoord trager, geen 2xx, geen geldig JSON-object (een lijst telt niet) of langer dan 20.000 tekens, dan negeren we het. Het gesprek begint dan gewoon zonder die gegevens en variabelen als {{customerName}} in de begroeting en {{inboundContext.customerName}} na het gesprek blijven leeg. Wat er wel is binnengekomen, zie je in de Inbox onder Technische details, bij Gegevens die voor het gesprek zijn opgezocht. Zie Inkomende webhook (vóór het gesprek).
Je endpoint ontvangt geen aanroep
Open het gesprek in de Inbox, klap Technische details open en kijk onder Wat de acties hebben gedaan. Deze lijst toont acties na het gesprek en wordt gevuld zodra het gesprek is afgelopen.
- De actie staat er niet bij. Ze staat uit, hoort bij een andere assistent of loopt niet Na het gesprek, of het gesprek loopt nog. Een gesprek via sms, WhatsApp of webchat loopt door totdat de assistent het afsluit, iemand op Gesprek beëindigen klikt of er een tijd niets is gebeurd: bij webchat de Time-out bij inactiviteit (standaard 60 minuten), bij sms en WhatsApp 6 uur, en met je team pas 18 uur na het laatste bericht, nooit zolang de klant op een antwoord wacht.
skipped: condition not met. De voorwaarde bij Onder welke voorwaarde moet dit na het gesprek gebeuren? was niet vervuld. Dat is ook zo als de klant niets heeft gezegd, tenzij dit veld leeg is.- Een fout als
url host did not resolve,url host is not allowedofurl address is not allowed. De URL klopt niet of is niet publiek bereikbaar:localhosten interne adressen werken niet. Gebruik tijdens het ontwikkelen een tunnel naar je lokale machine. HTTPmet een statuscode. Het verzoek is verstuurd en er kwam antwoord. Kijk verder in de logs van je endpoint.
Een actie Tijdens het gesprek loopt alleen als de assistent haar gebruikt; dat bepaalt hij met wat je invult bij Wanneer moet de assistent dit gebruiken?. Bij Uitproberen ontvangt je endpoint met Bellen en Chatten alleen iets als Acties echt uitvoeren aan staat, en die gesprekken staan niet in de Inbox. Echt bellen is een echt gesprek: de acties lopen echt en het gesprek staat wel in de Inbox.
Het antwoord van de tool wordt niet gebruikt
Antwoordt je endpoint correct maar doet de assistent er niets mee, dan ligt het aan Toelichting op het antwoord of de grootte van het antwoord: de assistent leest maximaal 6.000 tekens. Geeft je endpoint geen 2xx, dan krijgt de assistent alleen de statuscode te horen. Zie Problemen oplossen: prompt en tools en Webhook tijdens het gesprek.
De webhook na het gesprek komt twee keer binnen
Wij herhalen aanroepen niet automatisch, en een actie na het gesprek loopt één keer per gesprek; handmatig opnieuw uitvoeren kan niet. Ontvang je toch twee keer iets, dan staan er twee acties met dezelfde URL op de assistent (bijvoorbeeld na Dupliceren), of herhaalt iets tussen ons en je endpoint het verzoek, zoals een proxy of tunnel. Maak je verwerking idempotent door te dedupliceren op conversationId. Die zit in de standaardbody; gebruik je een eigen Body-sjabloon, zet er dan {{conversationId}} in. Zie Webhook na het gesprek.
Time-out
We wachten niet onbeperkt op je endpoint, en dat kun je niet instellen: 3 seconden vóór het gesprek, 6 seconden tijdens het gesprek en 8 seconden na het gesprek. Daarna wordt de aanroep afgebroken en niet opnieuw geprobeerd.
- Vóór het gesprek: het gesprek begint zonder die gegevens.
- Tijdens het gesprek: de assistent krijgt geen bruikbaar antwoord. Op een telefoongesprek krijgt hij helemaal geen antwoord op zijn verzoek, dus de beller kan stilte horen. Elke seconde telt, en de assistent heeft de gegevens nodig, dus houd het zo snel mogelijk.
- Na het gesprek: de actie staat met een foutmelding onder Wat de acties hebben gedaan. Antwoord daarom direct met een 2xx-status en verwerk de payload daarna asynchroon (wachtrij, achtergrondtaak).
Variabelen zijn leeg in de body
Welke variabelen er zijn, hangt af van het moment. Een onbekende of verkeerd gespelde naam wordt leeg.
- Vóór het gesprek:
fromNumber,toNumber,personNumber,agentNumber,company.name,company.website,company.phone,company.emailencompany.address. - Tijdens het gesprek: wat de assistent invult bij Parameters die de assistent invult, plus gegevens die bij de start zijn meegegeven (campagne of API). Ingebouwde variabelen als
{{personNumber}}blijven hier leeg; maak er een parameter van. - Na het gesprek: alle ingebouwde variabelen, zoals
summaryenpersonNumber, en je eigen variabelen.
Een eigen variabele definieer je op een actie die Na het gesprek loopt, bij Extra variabelen om te extraheren. Ze komt alleen gevuld in de payload als die actie aan staat, de omschrijving duidelijk is en het gegeven in het gesprek ter sprake kwam. Heeft de klant niets gezegd, dan blijven ook summary en je eigen variabelen leeg. company.address blijft leeg als je bedrijf zijn adres niet met klanten deelt. Zie Acties.
Make of n8n ontvangt niets
Een scenario in Make of een workflow in n8n luistert alleen als het actief staat; testmodus vangt maar één aanroep. Controleer bovendien of de webhook-URL niet is veranderd na het opnieuw aanmaken van de module en plak de actuele URL in de actie. Zie Make en n8n.
De header X-Yarla-Signature ontbreekt
Een GET-verzoek heeft geen body en wordt niet ondertekend. Alle andere methoden dragen de header, zonder dat je iets hoeft in te stellen: elk bedrijf heeft al een webhookgeheim. Wil je de handtekening controleren, zet Methode dan op POST, PUT, PATCH of DELETE. Het geheim vind je onder Instellingen → Koppelingen, op de kaart Webhookgeheim.
Nog steeds problemen?
Staat je probleem er niet bij of helpt de oplossing niet? Meld het via Een probleem melden en vermeld de conversationId, het tijdstip en de statuscode die je endpoint teruggaf.