Met webhook-acties kan uw AI-agent tijdens een gesprek externe diensten aanroepen.
Bijna elke webhook-actie past bij een van twee toepassingen:
Lezen – gegevens opvragen
Schrijven – gegevens wegschrijven
Als u uw configuratie vanaf het begin op deze twee toepassingen afstemt, is uw agent eenvoudiger te configureren, te testen en te vertrouwen.
Voordat u begint
Zorg dat u het volgende heeft:
Toegang tot de Webhook-functie in uw abonnement
Een werkend API-eindpunt
Authenticatiegegevens (bijv. API-sleutel of bearer-token)
Een korte lijst met velden die uw API vereist
Ga dan naar uw agent → Tools → schakel Webhook in → Actie toevoegen.
Toepassing 1: Gegevens lezen
Gebruik een lees-actie wanneer de agent informatie nodig heeft voordat hij kan antwoorden.
Typische scenario's
Bestelstatus controleren
Klantgegevens opvragen
Account- of boekingsgegevens valideren
Voorbeeld: Bestelstatus opvragen
Actie-instellingen
Veld | Waarde |
Titel | Bestelstatus opvragen |
HTTP-methode | GET |
URL |
|
Omschrijving | Haalt de actuele verzend- en leverstatus op voor een specifieke bestelling |
Wanneer te gebruiken | Gebruiken wanneer een klant vraagt waar zijn bestelling is of naar de levertijd informeert |
Inhoudstype | none |
Authenticatietype | header |
Authenticatieveld
Sleutel | Waarde |
Authorization |
|
Parameter
Naam | Locatie | Type | Verplicht | Voorbeeld |
orderId | query | string | ja | ORD-10458 |
Door de webhook verzonden verzoek
GET /v1/orders/status?orderId=ORD-10458 HTTP/1.1
Host: api.demo-shop.com
Authorization: Bearer demo_read_token_123
Voorbeeldrespons
{
"orderId": "ORD-10458",
"status": "shipped",
"estimatedDeliveryDate": "2026-09-05",
"carrier": "DHL",
"trackingNumber": "DHL-77890012"
}Toepassing 2: Gegevens schrijven
Gebruik een schrijf-actie wanneer de agent gegevens moet aanmaken, bijwerken of afsluiten in een ander systeem.
Typische scenario's
Supportticket aanmaken
Contactgegevens van klant bijwerken
Afspraak annuleren of verzetten
Voorbeeld: Supportticket aanmaken
Actie-instellingen
Veld | Waarde |
Titel | Supportticket aanmaken |
HTTP-methode | POST |
URL |
|
Omschrijving | Maakt een nieuw supportticket aan in het helpdesksysteem |
Wanneer te gebruiken | Gebruiken wanneer de klant een probleem meldt dat niet direct kan worden opgelost en akkoord gaat met het aanmaken van een ticket |
Inhoudstype | application/json |
Authenticatietype | header |
Authenticatieveld
Sleutel | Waarde |
Authorization |
|
Parameters
Naam | Locatie | Type | Verplicht | Voorbeeld |
ticket.subject | body | string | ja | Billing issue for invoice INV-983 |
ticket.description | body | string | ja | Customer says invoice amount is incorrect and requests review. |
customer.email | body | string | nee |
Door de webhook verzonden verzoek
POST /v1/tickets HTTP/1.1
Host: api.demo-helpdesk.com
Authorization: Bearer demo_write_token_456
Content-Type: application/json
{
"ticket": {
"subject": "Billing issue for invoice INV-983",
"description": "Customer says invoice amount is incorrect and requests review."
},
"customer": {
"email": "[email protected]"
}
}
Voorbeeldrespons
{
"ticketId": "TCK-22091",
"status": "open",
"priority": "normal",
"createdAt": "2026-09-02T10:14:22Z"
}Eén actie per taak
Combineer lees- en schrijfgedrag niet in één actie, tenzij uw API dit vereist.
Best practice: één actie om gegevens op te vragen, een aparte actie om gegevens weg te schrijven. Dit vermindert fouten en maakt het gedrag makkelijker te controleren.
Veldoverzicht
Geldt voor zowel lees- als schrijf-acties.
Actievelden
Veld | Doel |
Titel | Gebruiksvriendelijke naam |
HTTP-methode | GET, POST, PUT, PATCH of DELETE |
URL | Volledige URL, inclusief |
Omschrijving | Wat de actie doet |
Wanneer te gebruiken | Precies wanneer de agent deze actie moet kiezen |
Tip: Titel, Omschrijving en Wanneer te gebruiken zijn de belangrijkste signalen waarmee de agent de juiste actie kiest — investeer hier tijd in.
Invoerparameters
Voeg voor elke waarde die uw eindpunt verwacht een parameter toe.
Veld | Toelichting |
Naam | Te verzenden veldsleutel. Ondersteunt puntnotatie voor geneste waarden, bijv. |
Locatie | query, header of body |
Type | string, number, boolean, enum of array |
Verplicht | Inschakelen voor verplichte velden |
Omschrijving | Leg de verwachte waarde uit |
Voorbeeld | Optioneel, maar helpt de nauwkeurigheid van extractie |
Typespecifieke regels
Type | Regel |
string | Optionele minimale lengte/maximale lengte |
number | Optionele minimumwaarde/maximumwaarde, met schakelaar voor decimalen toestaan |
enum | Moet minstens één toegestane enum-waarde bevatten |
array | Itemtype moet string, number of boolean zijn |
Inhoudstype
Kies één optie:
application/json— als uw eindpunt JSON verwachtapplication/x-www-form-urlencodednone
Authenticatie
Kies waar auth-velden worden verzonden: none, header, body of query.
Als het authenticatietype header, body of query is, voeg dan minstens één sleutel/waarde-paar toe, bijvoorbeeld:
Sleutel | Waarde |
Authorization |
|
Problemen oplossen bij opslaan
Als het opslaan van een actie mislukt, controleer dan het volgende, gegroepeerd per onderdeel:
Actieniveau
Ontbrekende titel
Ongeldige methode (moet GET, POST, PUT, PATCH of DELETE zijn)
Ongeldige URL (moet een volledige URL zijn)
Dubbele actienaam
Authenticatie
Authenticatievelden zonder sleutel of waarde
Parameters
Ongeldige locatie (moet query, header of body zijn)
Ongeldig type
Enum-parameter zonder toegestane waarden
Dubbele parameternaam op dezelfde locatie
Ongeldige minimum/maximumwaarde-beperkingen (minimumwaarde mag niet groter zijn dan maximumwaarde)
Beveiliging en betrouwbaarheid
Gebruik aparte inloggegevens voor test en productie
Geef API-rechten volgens het principe van minimale bevoegdheden
Gebruik altijd HTTPS-eindpunten, nooit puur HTTP
Gebruik bij voorkeur header-authenticatie in plaats van query-authenticatie
Vermijd gevoelige waarden in voorbeelden van parameters
Maak schrijf-eindpunten waar mogelijk idempotent
Geef duidelijke API-foutmeldingen terug vanuit uw externe systeem
Beller verifiëren voordat gevoelige gegevens worden gedeeld
Geef nooit gevoelige informatie vrij op basis van alleen de beller-ID. Beller-ID is eenvoudig te vervalsen en mag niet worden behandeld als identiteitsbewijs.
Vraag in plaats daarvan om dezelfde soort verificatie die een menselijke medewerker zou gebruiken voordat accountgegevens worden vrijgegeven, bijvoorbeeld:
Laatste cijfers van het klant- of accountnummer
Geboortedatum
Postcode
Andere kennisgebonden gegevens die alleen de echte klant zou weten
Bouw deze controle in de actie zelf in: maak de verificatievelden verplichte parameters en stel in "Wanneer te gebruiken" in dat de agent deze informatie opvraagt en bevestigt voordat hij een actie aanroept die gevoelige gegevens teruggeeft.