Inhoud samenvatten met:
Een conversation-ended webhook verandert een afgeronde WhatsApp- of webchat in een verwerkbaar zakelijk event. In plaats van handmatig transcripten te kopiëren, kan een organisatie gestructureerde resultaten direct doorsturen naar een CRM, helpdesk, datawarehouse of automatiseringstool. De cruciale vraag is niet alleen of een webhook wordt verzonden. In productie moet de pipeline betrouwbaar blijven bij timeouts, dubbele events, mediabijlagen en gesprekken die meerdere dagen duren.
Nadat een chatgesprek is beëindigd, kan Famulor het volledige transcript, geëxtraheerde variabelen, inputvariabelen, klant- en afzendergegevens en tijdstempels leveren. WhatsApp-events kunnen ook afbeeldingen, audio, video en documenten als bijlagen bevatten. Deze blueprint laat zien hoe je die payload omzet in een integratie van enterprise-niveau.
Wat de conversation-ended webhook dekt
De webhook is ontworpen voor asynchroon werk na een gesprek. Typische uitkomsten zijn het aanmaken van een lead, het bijwerken van een ticket, het archiveren van een samenvatting of het starten van een follow-up workflow. Dit is anders dan een Mid-call Action: Mid-call Actions hebben toegang tot systemen tijdens een live interactie; de conversation-ended webhook draagt het resultaat over nadat een WhatsApp- of webwidgetgesprek is beëindigd.
| Datagebied | Belangrijkste velden | Typisch doel |
|---|---|---|
| Identiteit | conversation_id, assistant_id, type | Correlatie, routering en ontdubbeling |
| Resultaat | extracted_variables, input_variables | CRM-velden, kwalificatie en workflowbeslissingen |
| Geschiedenis | transcript, formatted_transcript | Traceerbaarheid, kwaliteitsborging en ondersteuningscontext |
| Tijd | timestamp, timestamp_unix, created_at, ended_at | Volgorde, SLA-meting en duur |
| Media | attachments met type, URL en bestandsnaam | Document- of beeldverwerking |
| Kanaal | customer_phone, customer_name, sender | Contactmatching en kanaalspecifieke logica |
De betrouwbare doelarchitectuur: snel bevestigen, later verwerken
Een webhook-endpoint moet zo min mogelijk synchroon werk verrichten. Het ontvangt het event, valideert de basisstructuur, slaat de ongewijzigde payload op en plaatst een taak in een wachtrij. CRM-updates, media-analyse, notificaties en grotere transformaties vinden daarna plaats. Hierdoor kan het endpoint snel een 2xx-respons teruggeven en worden onnodige herleveringen voorkomen.
- Event innemen: Beperk de payloadgrootte, parse JSON en valideer vereiste velden zoals
conversation_idenstatus. - Ongewijzigd opslaan: Sla de ruwe payload op met ontvangsttijd en een interne afleverstatus. Dit creëert een controleerbare bron voor toekomstige replays.
- Ontdubbelen: Voor conversation-ended events is
conversation_ideen nuttige zakelijke sleutel. De database mag niet dezelfde afronding twee keer als een nieuwe case registreren. - Asynchroon verwerken: Een worker voert veldtoewijzing, CRM-upserts, ticketcreatie, analytics en notificaties uit.
- Resultaat vastleggen: Leg het doelsysteem, API-resultaat, aantal pogingen en foutklasse vast. Dit verandert “webhook verzonden” in een meetbaar proces.
Retries zijn een vangnet, geen verwerkingslogica
Als het geconfigureerde endpoint faalt of geen 2xx-status teruggeeft, probeert Famulor de levering opnieuw na 30, 60 en 120 seconden. Na drie mislukte pogingen wordt de levering als mislukt gemarkeerd. Dit schema vangt korte netwerk- en platformincidenten op, maar vervangt geen wachtrij of idempotentie in het doelsysteem.
De kernregel is simpel: herlevering mag niet twee keer dezelfde zakelijke actie triggeren. Een CRM-upsert is veiliger dan een blinde aanmaakactie. Voor downstream-acties kan een speciale idempotentietabel conversation_id + action_name opslaan. De worker kan dan bepalen of hij al een ticket heeft aangemaakt, een e-mail heeft verzonden of een deal heeft bijgewerkt.
Replay en audittrails voor dagelijkse operaties
Famulor registreert het resultaat van een webhook-levering, inclusief de status en respons. Teams kunnen de webhook voor een individueel gesprek opnieuw verzenden, terwijl lijstweergaven ondersteuning bieden voor bulk-herevaluatie en herlevering. Dit is waardevol wanneer een CRM tijdelijk onbeschikbaar was of een veldtoewijzing is gecorrigeerd.
Een gecontroleerd replay-proces heeft drie regels nodig:
- Replay is idempotent: Het doelsysteem werkt hetzelfde record bij in plaats van duplicaten aan te maken.
- Origineel en transformatie blijven gescheiden: De ruwe payload is onveranderlijk; getransformeerde data krijgt een versie.
- Elke poging is zichtbaar: Registreer de tijd, initiator, transformatieversie en het resultaat.
De volledige veldreferentie en het retry-gedrag staan gedocumenteerd in de Famulor conversation-ended webhook-documentatie.
Welke systemen moet Voice AI verbinden?
Selecteer je tools en krijg een snelle integratieroute.
Famulor
Voice AI
Geselecteerde integraties: 4
Mediabijlagen veilig verwerken
WhatsApp-gesprekken kunnen afbeeldingen, audio, video en documenten bevatten. De webhook stelt een attachments-array bloot met een type, URL en bestandsnaam. Behandel deze URL's niet als vertrouwde interne bestanden. Een degelijke mediapipeline downloadt content aan de serverzijde, dwingt limieten af voor grootte en type, scant bestanden en bewaart ze alleen voor het opgegeven zakelijke doel.
- Valideer het werkelijke contenttype, niet alleen de bestandsextensie.
- Stel tijdslimieten in voor downloaden en verwerken.
- Scheid persoonsgegevens per rol en tenant.
- Log retentie, verwijdering en toegang.
- Verplaats mislukte analyses naar een dead-letter queue zonder het originele event te verliezen.
Voor uitgaande WhatsApp-berichten voegt de read receipts webhook statussen toe zoals sent, delivered, read en failed. Deze webhook is ondertekend met HMAC-SHA256. Verifieer de handtekening over de ongewijzigde request body en ontdubbel statusupdates op basis van message ID en status.
Technische events omzetten in zinvolle operationele statistieken
Een webhook-project is pas productieklaar als de status inzichtelijk is. Een nuttig operationeel dashboard kan beginnen met een korte set statistieken:
- Aandeel events geaccepteerd bij de eerste poging
- End-to-end tijd van einde gesprek tot succesvolle update in het doelsysteem
- Aantal en leeftijd van openstaande of mislukte taken
- Replay-percentage en meest voorkomende foutklasse
- Aandeel events met bijlagen en foutpercentage bij mediaverwerking
- Percentage ontbrekende vereiste velden in de CRM-mapping
Deze statistieken onthullen meer dan alleen infrastructuurproblemen. Een plotselinge stijging in ontbrekende kwalificatievelden kan erop wijzen dat een prompt of gespreksflow is veranderd. Webhook-observability verbindt daarom platformoperaties met de kwaliteit van Conversational AI.
Implementatiechecklist
- Schakel de conversation-ended webhook in voor de assistent en configureer een HTTPS-endpoint.
- Definieer het doelschema voor het CRM, de helpdesk of het datawarehouse.
- Creëer een opslag voor ruwe events en een unieke idempotentiesleutel.
- Definieer wachtrij-, worker-, retry- en dead-letter-gedrag.
- Beveilig het mediapad met regels voor content-type, grootte, malware en retentie.
- Test WhatsApp, webwidget, meerdaagse chats, menselijke overname en scenario's met bijlagen.
- Simuleer een mislukte levering en bewijs dat replay geen duplicaten creëert.
- Documenteer alarmering en eigenaarschap voor vastgelopen events.
Teams zonder automatiseringsarchitectuur kunnen beginnen met het Famulor Automation Platform of integreren via de API en hun eigen wachtrij. Voor WhatsApp-specifieke workflows biedt Famulor WhatsApp AI de kanaallaag.
FAQ
Hoe verschilt een conversation-ended webhook van een post-call webhook?
De conversation-ended webhook dekt chatgesprekken op WhatsApp en de webwidget. Telefoongesprekken gebruiken de post-call webhook. Beide kunnen downstream-workflows starten, maar hun payloads en kanaalmetadata verschillen.
Kan hetzelfde event vaker dan eens aankomen?
Ja. Herlevering is een normale mogelijkheid bij webhooks, vooral na een timeout of een niet-2xx respons. De ontvanger moet daarom elke verwerkingsstap idempotent maken.
Welke ID moet worden gebruikt voor ontdubbeling?
Voor de afronding van een chatgesprek is conversation_id de centrale zakelijke sleutel. Combineer voor individuele downstream-acties het gespreks-ID met een actienaam.
Moet de HTTP-handler het CRM direct bijwerken?
Dat kan werken voor een kleine test, maar een wachtrij is betrouwbaarder in productie. De handler kan snel bevestigen terwijl een worker externe systemen bijwerkt met onafhankelijke foutafhandeling.
Wat is de beste manier om te beginnen?
Begin met één bestemming en één duidelijk resultaat, zoals “upsert een gekwalificeerde lead in het CRM.” Voeg media-analyse, notificaties en extra automatiseringen pas toe nadat dat pad observeerbaar en replay-veilig is.
Auteur bij Famulor
