Webhooks

Wenn in Foudra etwas geschieht, kann Foudra ein anderes System durch eine Nachricht darüber informieren: Die Leitstelle erfährt, dass die Wartung eines Boots abgeschlossen ist, ein Shop erfährt, dass sich der Bestand geändert hat. Nur für Administratoren. Um Foudra etwas zu fragen oder etwas zu ändern, nutzen Sie die API; Webhooks dienen dazu, informiert zu werden.

Einen Webhook anlegen

Feld	Bedeutung
Name (Name)	Was am anderen Ende sitzt
URL (URL)	Wohin gesendet wird. Sie muss `https` verwenden und aus dem Internet erreichbar sein. Eine Adresse in einem privaten Netz wird abgelehnt, es sei denn, der Betreiber von Foudra hat diesen Host zugelassen
Events (Ereignisse)	Welche Ereignisse gesendet werden

Das Signaturgeheimnis wird einmal angezeigt, auf der folgenden Seite. Kopieren Sie es dann: Der Empfänger braucht es, um zu prüfen, dass eine Nachricht von Foudra stammt.

Send test (Test senden) sendet ein Ereignis ping. Switch off (ausschalten) beendet das Senden; Ereignisse, die eintreten, während ein Webhook ausgeschaltet ist, werden nicht für ihn aufbewahrt. Remove (entfernen) löscht ihn und behält seinen Zustellverlauf.

Ereignisse

Ereignis	Wann	`data`
`work_order.completed`	Die volle Menge eines Fertigungsauftrags ist gefertigt	`work_order` (`id`, `number`, `external_ref`, `quantity`, `quantity_done`, `due_at`, `notes`) und `part` (`id`, `part_number`, `name`, `is_stocked`)
`stock.changed`	Jede Lagerbewegung. Eine Umlagerung sind zwei	`movement` (`id`, `type`, `quantity_delta`, `reference_type`, `reference_id`, `occurred_at`), `part`, `location`, `on_hand_here`, `on_hand_total`
`ping`	Send test (Test senden)	`{"hello": "world"}`

Über external_ref eines Fertigungsauftrags weiß das andere System, worum es bei dem Auftrag ging. Legen Sie eine Wartung mit der Referenz „Hull 207“ an, und das Abschlussereignis sagt genau das.

Was gesendet wird

Ein POST mit einem JSON-Body:

{
  "id": 412,
  "type": "work_order.completed",
  "occurred_at": "2026-10-01T14:11:18Z",
  "text": "WO-00031 completed: 1 × Class 1 service (Hull 207).",
  "data": { "work_order": { "number": "WO-00031", "external_ref": "Hull 207" }, "part": { } }
}

text ist ein Satz für Menschen. Mengen sind Strings, wie in der API.

Header	Bedeutung
`X-Foudra-Event`	Der Ereignistyp
`X-Foudra-Event-Id`	Die ID des Ereignisses, dieselbe wie `id` im Body
`X-Foudra-Delivery`	Die ID dieser Zustellung
`X-Foudra-Signature`	`t=<unix time>,v1=<signature>`

Was der Empfänger tun muss

Schnell antworten, mit einem beliebigen 2xx-Status. Die eigentliche Arbeit erst danach erledigen. Keine Antwort innerhalb von 10 Sekunden gilt als Fehlschlag. Weiterleitungen werden nicht verfolgt.
Die Signatur prüfen. Berechnen Sie HMAC-SHA256 mit dem Signaturgeheimnis als Schlüssel über den Text <t>.<body>: den Wert t aus dem Header, einen Punkt, dann den Body genau so, wie er empfangen wurde. Vergleichen Sie das Ergebnis in Hex mit v1. Weisen Sie die Nachricht zurück, wenn sie sich unterscheiden oder t älter als ein paar Minuten ist.
Mit Wiederholungen rechnen. Eine Nachricht kann zweimal ankommen. Merken Sie sich die bearbeiteten Ereignis-IDs und ignorieren Sie eine, die Sie schon gesehen haben.

import hmac, hashlib, time

def verify(secret: str, header: str, body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    signed = parts["t"].encode() + b"." + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"]) and abs(time.time() - int(parts["t"])) < 300

Wenn es fehlschlägt

Eine fehlgeschlagene Zustellung wird nach 1 Minute erneut versucht, dann nach 5, 15 Minuten, einer Stunde, 3, 6 und 12 Stunden, und nach dem achten Versuch, etwa einen Tag später, aufgegeben. Recent deliveries (letzte Zustellungen) zeigt jede Zustellung, wie viele Versuche sie hatte und die letzte Antwort; Send now (jetzt senden) versucht eine sofort erneut.

Nach acht Fehlschlägen in Folge ohne Erfolg dazwischen wird der Webhook ausgeschaltet, und auf der Übersicht erscheint eine Aufgabe mit dem Grund. Beheben Sie den Fehler beim Empfänger, schalten Sie den Webhook wieder ein und nutzen Sie Send now für alles, was aufgegeben wurde.

Ereignisse werden ungefähr in der Reihenfolge gesendet, in der sie eintreten, ein erneut versuchtes kann aber nach einem späteren ankommen. Nutzen Sie occurred_at, wenn die Reihenfolge wichtig ist.