Webhooks

Een webhook stuurt elke nieuwe lead en elk nieuw ticket naar een adres van jou op het moment dat het binnenkomt, zodat een ander systeem het kan oppakken: een CRM, een helpdesk of een eigen automatisering. Webhooks horen bij Studio en hoger.

Opmerking. Webhooks worden getest en zijn nog niet voor elke werkruimte open. Waar ze dat niet zijn, staat de kaart Webhooks niet in Instellingen, en antwoordt de API met integrations_not_in_plan.

Een webhook toevoegen#

Druk in Instellingen, op de kaart Webhooks, op Nieuwe webhook en vul in:

• Adres: waar elke gebeurtenis heen gaat. Het moet met https:// beginnen, zonder poortnummer en zonder gebruikersnaam of wachtwoord erin, hoogstens 2.000 tekens hebben en bereikbaar zijn vanaf het internet. Een adres waarvan de naam naar een privénetwerk leidt, wordt geweigerd, en de naam wordt voor elke levering opnieuw opgezocht.
• Nieuwe lead en Nieuw ticket: welke gebeurtenissen je wilt ontvangen. Minstens één.
• Welke agents: Alle agents, wat ook geldt voor agents die je later toevoegt, of één agent, om alleen de leads en tickets van die agent te versturen.

Druk op Webhook aanmaken. Het volgende scherm toont het ondertekengeheim, waarmee je server elke levering controleert. Het wordt alleen deze keer getoond. Ben je het kwijt, verwijder de webhook dan en voeg hem opnieuw toe. Druk op Ik heb het gekopieerd als je dat gedaan hebt.

Een werkruimte heeft hoogstens 10 webhooks, en een adres maar één keer. Elke webhook staat in de lijst met zijn adres, zijn gebeurtenissen, zijn agents en hoe de laatste levering ging.

Wat er verstuurd wordt#

Elke gebeurtenis is een POST met een JSON-body:

{
  "id": "evt_4b1c9e2f7a8d4e0b9c3f",
  "type": "lead.created",
  "createdAt": "2026-09-25T10:15:00.000Z",
  "agentId": "ag_9f2c4e1b7d3a4c8e8b6f",
  "data": {
    "id": "lead_2e8a6c4b9d1f4a7e8c3b",
    "name": "Sam Jansen",
    "email": "sam@example.com"
  }
}

type is lead.created of ticket.created. data is de lead of het ticket precies zoals de API het teruggeeft, met alle velden; het voorbeeld hierboven is ingekort. De velden staan beschreven onder Leads en Tickets in de API-referentie.

Elk verzoek heeft deze headers:

De handtekening controleren#

De handtekening is een HMAC-SHA256, hexadecimaal, van het tijdstip uit t=, een punt en de body precies zoals hij binnenkwam, met het ondertekengeheim als sleutel. Controleer hem voor je een levering vertrouwt: iedereen die je adres kent, kan ernaar posten, maar alleen wij hebben het geheim. In Node.js:

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

// rawBody: the body as it arrived, before it is parsed as JSON.
function fromChatterLab(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((part) => part.split("=")));
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return (
    fresh &&
    typeof parts.v1 === "string" &&
    parts.v1.length === expected.length &&
    timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  );
}

Vergelijk in constante tijd, zoals timingSafeEqual doet, en weiger een levering waarvan het tijdstip meer dan een paar minuten van het jouwe afwijkt, zodat een opgenomen levering later niet opnieuw kan worden verstuurd.

Antwoorden, en wanneer het misgaat#

Antwoord binnen 5 seconden met een willekeurige 2xx-status. Wat je server verder terugstuurt, wordt niet gelezen. Een doorverwijzing wordt niet gevolgd en telt als mislukt. Een 410 zegt dat het adres voorgoed weg is, zoals Zapier antwoordt voor een verwijderde Zap: de webhook wordt meteen verwijderd, zonder nieuwe pogingen.

Een levering die mislukt, wordt opnieuw geprobeerd na 5 minuten, 15 minuten, 1 uur, 3 uur, 6 uur en 12 uur: 7 pogingen in bijna een dag. Elke nieuwe poging kan een paar minuten later komen dan dat. Mislukt ook de laatste poging, dan wordt de webhook uitgeschakeld en krijgt de eigenaar van de werkruimte een e-mail. Er gaat niets meer heen, en de leads en tickets van die dag worden later niet alsnog verstuurd: je vindt ze in het dashboard. Antwoordt je server weer, druk dan in Instellingen naast de webhook op Weer inschakelen.

Gebeurtenissen kunnen in een andere volgorde aankomen, en af en toe twee keer, bijvoorbeeld als je server het werk deed maar te laat antwoordde. Gebruik chatterlab-delivery om er een te herkennen die je al verwerkt hebt.

Leveringen bevatten persoonsgegevens, dus elke levering wordt 7 dagen nadat ze gemaakt is verwijderd, zodra ze afgeleverd is of opgegeven.

Via de API#

Webhooks kun je ook met een API-sleutel toevoegen en verwijderen: GET /webhooks, POST /webhooks, GET /webhooks/{id} en DELETE /webhooks/{id}, beschreven in de API-referentie. Een webhook weer inschakelen kan alleen in het dashboard. De MCP-server heeft geen tools voor webhooks: waar persoonsgegevens heen gaan, is niet aan een assistent om te veranderen.