Webhooks-API

Mit der Webhooks-API können Sie Ereignisse programmatisch abonnieren. Nutzen Sie sie für Sofort-Trigger im Zapier-Stil oder für individuelle Integrationen, die Echtzeit-Benachrichtigungen benötigen.

Hinweis: Die Webhooks-API setzt mindestens den Tarif Hobby mit aktiver Abrechnung voraus.

Endpunkte

Abonnement erstellen

POST /api/v1/webhooks/subscribe

Anfragetext

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

Parameter

Antwort

Erfolg (201):

{
  "id": "subscription-uuid"
}

Beispiel

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 löschen

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

Antwort

Erfolg (200): Gibt eine leere Antwort mit Status 200 zurück.

Beispiel

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

Agenten auflisten

Rufen Sie die verfügbaren Agenten ab, die Sie abonnieren können:

GET /api/v1/chatbots

Antwort

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

Webhook-Nutzlast

Wenn ein Ereignis eintritt, senden wir einen POST-Request an Ihre Ziel-URL:

Formularübermittlung

{
  "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"
}

Header

Wir fügen bei jeder Zustellung diese Header hinzu:

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>

Überprüfen Sie die Signatur anhand des exakten rohen UTF-8-Anfragetexts, bevor Sie das JSON parsen. Die Signaturprozedur und den Nutzlastkatalog finden Sie unter Webhook-Sicherheit.

URL-Anforderungen

Sicherheit

In der Produktion muss eine Abonnement-URL HTTPS verwenden. Außerhalb der Produktion wird auch HTTP akzeptiert – aber es sind ausschließlich http:- und https:-URLs erlaubt, und jede URL muss zusätzlich eine Prüfung auf öffentliches Ziel bestehen, die direkt an der URL selbst ansetzt: Sie lehnt localhost und ähnliche Loopback-Hostnamen, literale private und link-lokale Adressen sowie Cloud-Metadaten-Endpunkte ab.

Die vollständige Liste der Zielbeschränkungen finden Sie unter Webhook-Sicherheit; dort ist diese Regel maßgeblich beschrieben.

Validierung

Die URL wird beim Erstellen des Abonnements geprüft; URLs, die die obigen Prüfungen nicht bestehen, werden mit einem 400-Fehler abgelehnt, dessen Meldung die Produktionsanforderung nennt. Die Prüfung untersucht die URL genau so, wie sie geschrieben ist – sie löst keine Hostnamen auf. Geben Sie also den öffentlichen Endpunkt an, an dem Sie die Ereignisse tatsächlich empfangen möchten. Bei der Zustellung wird der Hostname einmal aufgelöst, jede aufgelöste Adresse muss öffentlich sein, und die Verbindung wird an genau diese Adressen gebunden – ein Hostname, der auf eine private oder interne Adresse auflöst (auch wenn sie sich zwischen Auflösung und Verbindungsaufbau ändert), wird nie kontaktiert; der Versuch wird als target_blocked protokolliert.

Zuverlässigkeit

Anforderungen an die Antwort

Ihr Endpunkt sollte:

• Innerhalb von 10 Sekunden mit einem 2xx-Status antworten
• Doppelte Zustellungen verarbeiten (idempotent)

Fehlerbehandlung

• Fehlgeschlagene Zustellungen werden nach der ersten Anfrage fünfmal wiederholt
• Ein erschöpftes Ereignis erhöht die Serie aufeinanderfolgender Fehlschläge um eins
• Mindestens 10 erschöpfte Ereignisse innerhalb von sieben Tagen deaktivieren ein Abonnement automatisch
• Inhaber können Abonnements in den Webhook-Einstellungen reparieren und erneut aktivieren
• Die Zustellung erfolgt mindestens einmal; verwenden Sie eventId zur Idempotenz und verlassen Sie sich nicht auf die Reihenfolge

Fehlerantworten

Zapier-Integration

Diese Endpunkte treiben unsere Zapier-Integration an. Wenn Sie Agentkit mit Zapier verbinden:

1. Zapier ruft /api/v1/auth auf, um Ihren API-Schlüssel zu überprüfen
2. Zapier ruft /api/v1/chatbots auf, um Ihre Agenten aufzulisten
3. Wenn Sie einen Trigger aktivieren, ruft Zapier /api/v1/webhooks/subscribe auf
4. Ereignisse werden an die Webhook-URL von Zapier zugestellt
5. Wenn Sie deaktivieren, ruft Zapier DELETE für das Abonnement auf

Um ohne eigenen Code zu integrieren, nutzen Sie Zapier direkt anstelle dieser APIs.

Zapier einrichten →

Codebeispiel

Node.js-Abonnementverwaltung

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;
  }
}

Nächste Schritte

• Lead-Erfassung einrichten, um Ereignisse zu generieren
• Webhooks in der Oberfläche konfigurieren für die Einrichtung im Dashboard
• Mit Zapier verbinden für über 5.000 Integrationen