Documentatie

Webhooks

Stuur ondertekende realtime events naar externe diensten.

Webhooks sturen ondertekende meldingen wanneer leads, formulieren, gesprekken of escalaties veranderen. Hiervoor is een Hobby-plan of hoger met actieve facturering vereist.

Een endpoint configureren

Open Instellingen → Webhooks van een agent, kies één of meer events, voer een openbaar HTTPS-endpoint in en maak de abonnementen aan. Agentkit houdt één ondertekeningsgeheim aan voor alle event-rijen op hetzelfde endpoint. Accounteigenaren kunnen dit onthullen of roteren vanaf de endpointkaart.

Ondersteunde eventnamen zijn:

  • lead_created
  • form_submission (verouderd alias voor lead)
  • custom_form_submitted
  • conversation_started
  • conversation_ended
  • escalation_created

conversation_ended wordt verzonden nadat er 30 minuten lang geen bericht is geweest. Het transcript is een onveranderlijke snapshot van maximaal 200 berichten, waarbij elk bericht een maximum van 2.000 tekens heeft. Gesprekken die alleen in de Playground plaatsvinden en gesprekken zonder bericht van de gebruiker worden niet verzonden. Transcriptanalyse is momenteel null.

Envelope

Elk event gebruikt dezelfde stabiele envelope:

{
  "event": "conversation_started",
  "eventId": "evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a",
  "timestamp": "2026-07-14T13:05:02.000Z",
  "data": {
    "conversationId": "0b8e43d2-6cdf-42a8-8df1-a17f082df99f",
    "conversationReferenceId": "a1b2c3d4e5f6a7b8",
    "chatbotId": "d21c2aca-52d7-4056-a7d6-805713d3d39c",
    "source": "widget",
    "startedAt": "2026-07-14T13:05:02.000Z"
  }
}

Gebruik eventId als je idempotentiesleutel. Bezorging gebeurt minstens één keer en de volgorde is niet gegarandeerd. Bij retries worden dezelfde event-ID, tijdstip van optreden en JSON-bytes hergebruikt.

Handtekeningen verifiëren

Bezorgingen bevatten:

X-Agentkit-Event: conversation_started
X-Agentkit-Event-Id: evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a
X-Agentkit-Signature: t=1784043902,v1=<hex-hmac-sha256>

Lees de request body als ruwe UTF-8-tekst. Parse t en v1, bereken HMAC-SHA256 met het endpointgeheim over de exacte bytes van t + "." + rawBody, en vergelijk de digests met een constant-time functie. Parse en herserialiseer de JSON niet vóór verificatie. Wijs verlopen timestamps af volgens je eigen replaybeleid.

import { createHmac, timingSafeEqual } from 'node:crypto';

const expected = createHmac('sha256', process.env.AGENTKIT_WEBHOOK_SECRET!)
  .update(`${timestamp}.${rawBody}`, 'utf8')
  .digest('hex');

const valid = timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex'));

Betrouwbaarheid en resultaten

Geef binnen 10 seconden een 2xx-status terug. Een non-2xx-respons, timeout of netwerkfout wordt na het eerste verzoek vijf keer opnieuw geprobeerd (normaal gesproken zes pogingen in totaal) met QStash-backoff. De instellingenpagina toont de laatste 20 definitieve resultaten.

Eén uitgeputte event verhoogt de foutenreeks slechts één keer, ongeacht het aantal pogingen of dubbele callbacks. Een abonnement wordt pas automatisch uitgeschakeld na minstens 10 opeenvolgende uitgeputte events verspreid over minstens zeven dagen. Eigenaren ontvangen één meldingsbericht dat opnieuw kan worden verzonden en kunnen het abonnement na herstel weer inschakelen. Een geslaagd event zet de reeks terug naar nul.

Endpoint-URL's moeten HTTP of HTTPS gebruiken, moeten openbaar bereikbaar zijn en mogen niet wijzen naar localhost, private/link-local IP-bereiken of cloud-metadata-endpoints. In productie is HTTPS verplicht. Bij de aflevering lost Agentkit de hostnaam één keer op, vereist dat elk opgelost adres openbaar is en pint de verbinding vast op die adressen, zodat DNS-rebinding een aflevering niet naar een intern adres kan omleiden.

Schema activeren

De code voor het opruimen van inactieve gesprekken wordt standaard uitgeschakeld uitgeleverd. Een beheerder kan na deployment pnpm --filter chatbots setup:idle-conversation-webhooks controleren en uitvoeren. Het commando maakt het 15-minuten-QStash-schema aan; het mergen van code creëert of activeert dit niet vanzelf.

Volgende stappen