Friendship Tracker

Webhooks

Abonniere einen HTTPS-Endpunkt für Friendship Tracker-Ereignisse.

Webhooks lassen deinen eigenen Dienst auf Änderungen in Friendship Tracker reagieren, sobald sie passieren - ohne Polling. Jedes Abo wählt die gewünschten Ereignisse und sendet eine signierte JSON-Nutzlast an deine URL. Fehlgeschlagene Zustellungen werden mit exponentieller Verzögerung wiederholt (bis zu 12 Versuche); ein Abo, das dauerhaft fehlschlägt, wird automatisch pausiert, damit dein Empfänger nicht in eine Schleife läuft. Verwalte deine Abos im Webhooks-Menü oben.

So funktioniert's

  1. Erstelle ein Abo im Webhooks-Menü oben rechts. Wähle Endpunkt-URL und die Ereignisse, die du empfangen willst.
  2. Kopiere den Schlüssel. Der whsec_…-Wert wird genau einmal beim Anlegen (und beim Rotieren) angezeigt.
  3. Verifiziere jede Zustellung mit dem Schlüssel + dem Header X-Webhook-Signature. Dein Endpunkt antwortet mit 2xx innerhalb von 10 Sekunden.
  4. Fehler werden wiederholt. Bis zu 12 Versuche mit exponentieller Verzögerung; danach wird das Abo automatisch pausiert.

Was ist im Vertrag enthalten?

Jede Nutzlast signieren

Jede Zustellung trägt X-Webhook-Signature: v1=<hex>,t=<unix>. Verifiziere mit hmac_sha256(secret, "v1." + t + "." + body). Verwerfe Anfragen, deren t mehr als 300 Sekunden von deiner Server-Uhr abweicht, um Replays zu blockieren. Der Schlüssel wird beim Anlegen und Rotieren genau einmal angezeigt.

Idempotente Empfänger

Wiederholungen werden mit derselben id (und denselben Daten) ausgelöst, aber pro Versuch mit einem neuen X-Webhook-Delivery-Header. Dedupliziere anhand der id, damit ein wiederholter Erfolg den Effekt nicht doppelt auslöst.

Innerhalb von 10 Sekunden antworten

Antworte innerhalb von 10 Sekunden mit einem beliebigen 2xx-Status, um den Empfang zu bestätigen. Alles andere (Timeout, 4xx, 5xx) zählt als Fehler und löst die nächste Wiederholung aus.

Vor dem Live-Schalten testen

Nutze die Schaltfläche 'Test senden' auf der Webhooks-Seite, um eine synthetische webhook.test-Zustellung zu feuern. So kannst du Signaturprüfung und Parser verifizieren, ohne auf ein echtes Ereignis warten zu müssen.

Beispiele

{
  "id":        "<delivery uuid>",
  "event":     "<type>.<after_create|after_update|after_delete>",
  "type":      "<type>",
  "app":       "friendship",
  "timestamp": 1714501234,
  "attempt":   1,
  "actor_id":  "<user id or null>",
  "object":    { "id": "…", "data": { } }
}

Ereignisnamen

Wir verwenden <typ>.<after_create|after_update|after_delete> als Ereignisnamen. Ein Abo kann auch <typ>.* (alle Ereignisse eines Typs) oder * (alles, was passiert) feuern. Der synthetische webhook.test-Wert wird ausschließlich von der Schaltfläche 'Test senden' verwendet.

Schlüssel rotieren ohne Datenverlust

Der Button 'Schlüssel rotieren' eröffnet standardmäßig eine Übergangsfrist von einer Woche. In dieser Zeit wird jede Zustellung mit zwei Signaturen versehen - dem neuen und dem vorherigen Schlüssel:

X-Webhook-Signature: v1=<hex new>,v1=<hex previous>,t=<unix>

Iteriere alle v1=-Einträge im Header und akzeptiere die Zustellung, sobald einer mit deinem konfigurierten Schlüssel übereinstimmt. So kannst du den neuen Wert in Ruhe ausrollen, ohne dass Ereignisse verloren gehen. Nach Ablauf der Frist wird nur noch mit dem aktuellen Schlüssel signiert. Ein vorzeitiger Widerruf ist über 'Vorherigen Schlüssel sofort widerrufen' möglich, falls der alte Wert kompromittiert wurde.