Webhooks-API

Met de Webhooks-API kun je je programmatisch abonneren op gebeurtenissen. Gebruik het voor directe triggers in Zapier-stijl of voor aangepaste integraties die realtime meldingen nodig hebben.

Let op: de Webhooks-API vereist een Hobby-plan of hoger met actieve facturering.

Endpoints

Abonnement aanmaken

POST /api/v1/webhooks/subscribe

Request-body

{
  "event": "form_submission",
  "targetUrl": "https://your-server.com/webhook",
  "chatbotId": "123e4567-e89b-12d3-a456-426614174000"
}

Parameters

Respons

Succes (201):

{
  "id": "subscription-uuid"
}

Voorbeeld

curl -X POST 'https://your-domain.com/api/v1/webhooks/subscribe' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "form_submission",
    "targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef",
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000"
  }'

Abonnement verwijderen

DELETE /api/v1/webhooks/subscribe/[id]

Respons

Succes (200): Geeft een lege respons terug met status 200.

Voorbeeld

curl -X DELETE 'https://your-domain.com/api/v1/webhooks/subscribe/sub_abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Agents weergeven

Beschikbare agents opvragen waarop je je kunt abonneren:

GET /api/v1/chatbots

Respons

{
  "chatbots": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Support Bot",
      "url": "https://your-domain.com/chat/support-bot"
    }
  ]
}

Webhook-payload

Wanneer er een gebeurtenis plaatsvindt, sturen we een POST-request naar je doel-URL:

Gebeurtenis: formulierinzending

{
  "event": "form_submission",
  "eventId": "evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a",
  "data": {
    "id": "lead-uuid",
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+1234567890",
    "conversationId": "conv_abc123",
    "createdAt": "2025-01-10T12:00:00Z"
  },
  "timestamp": "2025-01-10T12:00:00Z"
}

Headers

Bij elke aflevering sturen we deze headers mee:

Content-Type: application/json
User-Agent: AgentkitWebhook/2.0
X-Agentkit-Event: form_submission
X-Agentkit-Event-Id: evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a
X-Agentkit-Signature: t=<unix-seconds>,v1=<hex-hmac-sha256>

Verifieer de handtekening aan de hand van de exacte, ruwe UTF-8-requestbody voordat je de JSON parseert. Zie Webhookbeveiliging voor de ondertekeningsprocedure en de payloadcatalogus.

URL-vereisten

Beveiliging

In productie moet een abonnements-URL HTTPS gebruiken. Buiten productie wordt ook HTTP geaccepteerd — maar alleen http:- en https:-URL's zijn ooit toegestaan, en elke URL moet bovendien een publieke-bestemmingscontrole op de URL zelf doorstaan, die localhost en vergelijkbare loopback-hostnamen, letterlijke privé- en link-local-adressen en cloud-metadata-endpoints weigert.

Zie Webhookbeveiliging voor de volledige lijst met bestemmingsbeperkingen; dat is de canonieke beschrijving van deze regel.

Validatie

De URL wordt gecontroleerd op het moment dat je het abonnement aanmaakt; URL's die de bovenstaande controles niet doorstaan worden geweigerd met een 400-fout waarvan het bericht de productievereiste noemt. De controle beoordeelt de URL zoals die is geschreven — ze lost geen hostnamen op, dus richt je abonnement op het publieke endpoint waar je de events daadwerkelijk wilt ontvangen. Bij de aflevering wordt de hostnaam één keer opgelost, moet elk opgelost adres openbaar zijn en wordt de verbinding vastgepind op die adressen — een hostnaam die naar een privé- of intern adres verwijst (ook als dat tussen opzoeken en verbinden verandert) wordt nooit benaderd; de poging wordt vastgelegd als target_blocked.

Betrouwbaarheid

Eisen aan je respons

Je endpoint moet:

• Binnen 10 seconden een 2xx-status teruggeven
• Dubbele afleveringen afhandelen (idempotent)

Foutafhandeling

• Mislukte afleveringen worden na het eerste verzoek vijf keer opnieuw geprobeerd
• Eén uitgeputte gebeurtenis verhoogt de opeenvolgende foutenreeks met precies één
• Zodra minstens 10 uitgeputte gebeurtenissen zich binnen zeven dagen voordoen, wordt een abonnement automatisch uitgeschakeld
• Eigenaren kunnen abonnementen herstellen en opnieuw inschakelen vanuit de webhookinstellingen
• Aflevering gebeurt minstens één keer; gebruik eventId voor idempotentie en ga niet uit van een vaste volgorde

Foutmeldingen

Zapier-integratie

Deze endpoints vormen de basis van onze Zapier-integratie. Wanneer je Agentkit koppelt aan Zapier:

1. Zapier roept /api/v1/auth aan om je API-sleutel te verifiëren
2. Zapier roept /api/v1/chatbots aan om je agents op te halen
3. Wanneer je een trigger inschakelt, roept Zapier /api/v1/webhooks/subscribe aan
4. Gebeurtenissen worden afgeleverd op de webhook-URL van Zapier
5. Wanneer je de trigger uitschakelt, roept Zapier DELETE aan op het abonnement

Wil je zonder te programmeren integreren, gebruik dan rechtstreeks Zapier in plaats van deze API's.

Zapier instellen →

Codevoorbeeld

Node.js-abonnementsbeheer

class WebhookManager {
  constructor(apiKey, baseUrl) {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
  }

  async subscribe(chatbotId, targetUrl, event = 'form_submission') {
    const response = await fetch(`${this.baseUrl}/api/v1/webhooks/subscribe`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ event, targetUrl, chatbotId }),
    });

    if (!response.ok) {
      throw new Error(`Subscribe failed: ${response.status}`);
    }

    return response.json();
  }

  async unsubscribe(subscriptionId) {
    const response = await fetch(
      `${this.baseUrl}/api/v1/webhooks/subscribe/${subscriptionId}`,
      {
        method: 'DELETE',
        headers: { 'Authorization': `Bearer ${this.apiKey}` },
      },
    );

    return response.ok;
  }
}

Volgende stappen

• Leads verzamelen instellen om gebeurtenissen te genereren
• Webhooks configureren in de interface via het dashboard
• Verbinden met Zapier voor 5.000+ integraties