Übersicht über Webhooks

Sursa erfasst ein Ereignis für jede wichtige Änderung: Eine Karte wird veröffentlicht, geprüft oder archiviert, eine Ankündigung wird gelesen, eine Frage bleibt unbeantwortet. Sie können Ereignisse auf zwei Arten empfangen und beide kombinieren:

Beide liefern dieselben Ereignisse mit denselben IDs. Jedes Ereignis wird 30 Tage im Feed aufbewahrt, unabhängig davon, ob ein Webhook es abonniert hatte.

Das Ereignis

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "card.updated",
  "created_at": "2026-10-24T10:00:03Z",
  "org_id": 1,
  "api_version": "1.60.0",
  "sequence": 1042,
  "object": {"type": "card", "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"},
  "payload": "full",
  "data": {
    "card": {"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "collection": "support", "version": 4},
    "actor_id": 7,
    "previous_attributes": {"title": "Refunds"}
  },
  "test": false
}

data enthält nur, was jede Person, die das Objekt lesen darf, auch über die API sehen könnte. Es enthält nie Zugriffslisten, Berechtigungen anderer Personen oder verborgene Felder. Gründe in Ereignissen sind kurze, neutrale Codes wie no_hits, restricted oder index_failed.

Ereignistypen

Ereignisse decken diese Bereiche ab:

Die vollständige Liste mit dem Schema und einem Beispiel für jedes Ereignis steht im Ereigniskatalog der API-Referenz. GET /v1/webhooks/catalog gibt die Typen zurück, die in Ihrer Installation verfügbar sind.

Mit der Zeit kommen neue Ereignistypen hinzu, und bestehende Ereignisse erhalten neue Felder. Ereignistypen werden nie umbenannt oder entfernt. Ihr Empfänger muss Typen und Felder überspringen, die er nicht kennt.

Wer was erhält

Ein Endpunkt erhält ein Ereignis nur, wenn das Objekt des Ereignisses für den Endpunkt sichtbar ist – genauso wie für einen API-Schlüssel: nach seiner Rolle, seinem Datenprofil und seinen Sammlungen. Ein Endpunkt, der auf die Sammlung support beschränkt ist, erhält nie Ereignisse zu Karten in finance. Ereignisse zu Personen, Schlüsseln, Quellen, Importen, Jobs, Exporten, Abrechnung, Anwendungen und zu den Webhooks selbst gehen nur an Endpunkte mit der Rolle admin.

Innerhalb dieses Rahmens wählt jeder Endpunkt seine Ereignisse:

• nach Typ, mit Masken: card.* für jedes Kartenereignis, * für jedes Ereignis;
• nach Sammlung und nach Tag, bei Kartenereignissen.

Der Payload-Modus eines Endpunkts ist full (das Ereignis mit data, der Standard) oder thin (das Ereignis ohne data: Ihr Empfänger liest das Objekt mit seinem eigenen Schlüssel über die API und sieht immer dessen aktuellen Zustand).

Zustellung in Kürze

• Ein HTTPS-POST mit dem Ereignis als JSON, signiert mit dem Secret des Endpunkts in zwei Formaten: Standard Webhooks (webhook-signature) und das frühere X-KB-Signature.
• Jede Antwort 2xx innerhalb von 10 Sekunden gilt als Erfolg.
• Ein Fehlschlag wird fast drei Tage lang mit wachsenden Pausen wiederholt. Retry-After in einer Antwort 429 oder 503 wird beachtet; 410 deaktiviert den Endpunkt; 10 Fehlschläge in Folge pausieren ihn, bis er fortgesetzt wird.
• Zustellungen an einen Endpunkt werden streng der Reihe nach gesendet. Ein langsamer Endpunkt verzögert andere Endpunkte nicht.
• Dasselbe Ereignis kann mehr als einmal ankommen: Verwerfen Sie Duplikate anhand von webhook-id.

Webhooks empfangen führt durch einen vollständigen Empfänger mit Signaturprüfung in Node.js, Python und Go.

Endpunkte verwalten

Zum Verwalten von Endpunkten ist ein Schlüssel mit der Rolle admin und dem Scope webhooks:manage nötig oder eine Administratorin bzw. ein Administrator in der Administrationsoberfläche. Eine Organisation kann bis zu 20 Endpunkte haben. Webhooks sind Teil des Tarifs der Organisation; ohne sie antworten diese Endpunkte mit 403 und dem Code webhooks.feature_disabled.