Ein Webhook ist eine URL auf deinem Server, die wir aufrufen, wenn etwas passiert, zum Beispiel wenn eine Frage alle Antworten hat. Dein Code muss dann nicht ständig nachfragen.

Einrichten

  1. Wähl unter Entwickler Webhooks und füg dann einen Endpunkt hinzu.
  2. Gib eine HTTPS-URL ein und wähl die gewünschten Ereignisse, zum Beispiel question.completed.
  3. Kopier das Signatur-Secret. Es wird nur einmal angezeigt.
  4. Schick einen Test, um zu prüfen, dass dein Server ihn empfängt und die Signatur stimmt.

Du kannst Endpunkte auch per Code verwalten: Siehe den letzten Abschnitt unten.

Ereignisse

Fragen reserviert, abgeschlossen, unvollständig, abgebrochen oder abgelehnt; Credits gekauft, knapp oder bald ablaufend; Reklamationen entschieden; und eine Verbindung nahe ihrem Limit. Ein Test, den du schickst, kommt als webhook.test an. Um ohne eigenen Server auf diese Ereignisse zu reagieren, nutz die Zapier-App.

Jeder Endpunkt behält die Payload-Version, mit der er erstellt wurde. Innerhalb einer Version fügen wir nur Felder hinzu; wir entfernen oder ändern nie eines. Die Webhook-Dokumentation (auf Englisch) verlinkt die genauen Felder jedes Ereignisses.

Webhooks für ein Team

Ein Endpunkt gehört zu dem Konto, in dem du ihn erstellt hast. Erstellst du ihn, während du in einem Team arbeitest, bekommt er Ereignisse zu den Fragen aller Mitglieder in diesem Team und zu den Credits des Teams. Wer gefragt hat, bekommt das Ereignis zusätzlich auf den eigenen Endpunkten.

In einem Team können Inhaber und Admins Endpunkte hinzufügen, ändern und entfernen. Mitglieder können sie und ihre Zustellungen sehen.

Nur bestimmte Fragen

Du kannst einem Endpunkt einen Filter geben, damit er Ereignisse zu Fragen nur für ausgewählte Projekte oder Labels bekommt. Ereignisse, die keine Frage betreffen, zum Beispiel knappe Credits, kommen immer an.

Die Signatur prüfen

Jede Zustellung ist auf zwei Arten mit deinem Secret signiert, du kannst also prüfen, was dir besser passt:

  • die Header webhook-id, webhook-timestamp und webhook-signature von Standard Webhooks, die viele Webhook-Bibliotheken für dich prüfen;
  • unser Header x-50heads-signature mit einem Zeitstempel und einem HMAC-SHA256 des Bodys.

Prüf eine davon, bevor du dem Inhalt vertraust. Die Webhook-Dokumentation (auf Englisch) hat Code zum Kopieren in TypeScript, Python und Go.

Wenn dein Secret vor dem 10. Oktober 2026 erstellt wurde und du eine Standard-Webhooks-Bibliothek nutzt, rotier das Secret einmal, damit die Bibliothek es akzeptiert.

Das Secret wechseln

Beim Rotieren bekommst du ein neues Secret, das nur einmal angezeigt wird. Das alte funktioniert daneben noch 24 Stunden weiter, außer du wählst eine andere Dauer, bis zu 7 Tage. In dieser Zeit ist jede Zustellung mit beiden signiert, damit nichts fehlschlägt, während du deinen Server umstellst.

Wenn du glaubst, dass ein Secret bekannt geworden ist, rotier es ohne Überschneidung. Das alte Secret hört dann sofort auf.

Wiederholungen und erneutes Senden

Antworte innerhalb von zehn Sekunden mit einem 2xx-Status. Sonst versuchen wir es mit zunehmendem Abstand erneut, achtmal über etwa 24 Stunden. Das Protokoll Zustellungen zeigt jeden Versuch, und du kannst jede Zustellung erneut auslösen.

Zustellungen können gelegentlich doppelt oder in falscher Reihenfolge ankommen. Nutz die Ereignis-ID, um Wiederholungen zu ignorieren.

Wenn fünf Zustellungen hintereinander nach allen Versuchen fehlschlagen, schalten wir den Endpunkt ab und schicken dir eine E-Mail. Die E-Mail verlinkt auf den Endpunkt unter Webhooks in Entwickler. Dort steht er als Aus, mit dem Zeitpunkt und dem Grund. Sobald dein Server wieder läuft, wähl Fortsetzen und sende dann die verpassten Zustellungen erneut. An einen abgeschalteten Endpunkt wird nichts gesendet.

Du kannst bei jedem Endpunkt auch Pausieren wählen, um Zustellungen für eine Weile zu stoppen. Er steht dann genauso als aus da, und Fortsetzen startet ihn wieder. Den Endpunkt eines Teams können nur Inhaber oder Admins pausieren oder fortsetzen.

Webhooks per Code verwalten

Ein Schlüssel oder ein verbundener KI-Assistent kann Endpunkte auflisten, hinzufügen, ändern, testen und Zustellungen erneut senden, wenn er diese Berechtigungen hat:

  • webhooks:read: Endpunkte und ihre Zustellungen sehen.
  • webhooks:write: Endpunkte hinzufügen, ändern, ihr Secret rotieren, testen, Zustellungen erneut senden und Endpunkte entfernen.

Sie werden nie automatisch vergeben, weil sie bestimmen, wohin die Ereignisse zu deinen Fragen gehen. Hak sie an, wenn du einen Schlüssel erstellst. Eine App muss sie anfragen, und du siehst sie aufgelistet, bevor du zustimmst. Schlüssel, die vor den Berechtigungen erstellt wurden, können keine Webhooks verwalten: Erstell einen neuen Schlüssel. Die Webhook-Dokumentation (auf Englisch) hat die Details.