betool

Dokumentation

HTTP-Webhook

Generischer Empfang signierter HTTP-Ereignisse von beliebigen Systemen.

Der Kanal Webhook ist der generische Einstiegspunkt, um jedes System anzubinden, das einen HTTP-POST ausführen kann. Es ist die Option der Wahl, wenn für Ihre Quelle kein dedizierter Kanal existiert.

Wann Sie ihn verwenden

  • Ein internes Werkzeug anbinden (ERP, Geschäftsanwendung, Zahlungs-Gateway).
  • Ereignisse von einer Drittplattform empfangen, die generische Webhooks bietet.
  • Eine Pipeline aus einem externen Cron-Job oder einer CI auslösen.

Konfiguration

  1. Konfigurieren Sie im Editor des Modells den Knoten Start mit einem Empfänger Eingehender Webhook.
  2. betool generiert eine öffentliche URL (https://platform.betool.ai/entries/webhook/<token>).
  3. (Empfohlen) Legen Sie in der Konfiguration des Empfängers ein HMAC-Secret fest.

Ist ein Secret konfiguriert, muss Ihr System den Roh-Body jeder Anfrage signieren — HMAC-SHA256(secret, body), hexadezimal — und die Signatur im Header X-Webhook-Signature übergeben, in der Form sha256=<hex> oder nur <hex>. Name des Headers und Algorithmus (sha256, sha384, sha512) sind konfigurierbar, zum Beispiel um der Konvention X-Hub-Signature-256 von GitHub zu folgen. Jede Anfrage ohne gültige Signatur wird dann abgelehnt (401).

Nur dieses Format wird geprüft: ein hexadezimaler HMAC des Roh-Bodys. Eine Signatur mit Zeitstempel (t=…,v1=…) oder in Base64-Kodierung wird nicht erkannt.

Nutzlastformat

Sie senden beliebiges JSON. betool schränkt die Struktur nicht ein. Die Nutzlast wird der Pipeline unter webhook.payload (mit ihren Unterschlüsseln) bereitgestellt; Header, Methode und Query-String sind ebenfalls unter webhook.headers, webhook.method und webhook.query verfügbar.

Der Body wird gemäß seinem Content-Type gelesen: JSON geparst, Formular (application/x-www-form-urlencoded) als Dictionary, XML und text/* als Rohtext, multipart/form-data als Felder + angehängte Dateien (webhook.payload._files), jeder andere Typ (PDF, Bild, Archiv …) als Datei gespeichert. Ein mit gzip komprimierter Body wird dekomprimiert. Maximale Größe: 50 MB (413 darüber).

Beispiel:

curl -X POST https://platform.betool.ai/entries/webhook/abc123 \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=$SIGNATURE" \
  -d '{
    "type": "order.created",
    "order_id": "ord_42",
    "amount_cents": 9900,
    "customer_email": "client@exemple.com"
  }'

Die Pipeline kann dann einen Agent verdrahten, der webhook.payload.customer_email und webhook.payload.amount_cents direkt liest.

Antwort

Zwei Antwortmodi (response_mode): sync (Standard) blockiert bis zum Ergebnis der Pipeline und liefert es in der Antwort zurück; ack gibt sofort 202 Accepted zurück, nachdem das Ereignis in eine dauerhafte Warteschlange gestellt wurde (die Pipeline läuft danach, mit Wiederholungen) — die Wahl für Anbieter, die früh in ein Timeout laufen.

GET-Aufrufe (Option)

Standardmäßig wird nur POST akzeptiert: ein GET erhält 405. Für einen Partner, der eine Abfrage per GET ?action=… vorschreibt, aktivieren Sie Auch GET akzeptieren (allow_get). Die Query-String wird dann zu webhook.payload, in derselben Form wie ein Formular-POST: Die Pipeline muss nicht wissen, welche Methode verwendet wurde. Ein GET trägt keinen Body (mit 400 abgelehnt) und ist nicht mit der HMAC-Signatur kompatibel (mit 405 abgelehnt, solange ein Secret hinterlegt ist). Eine in der Query übergebene Kennung erscheint in den Zugriffsprotokollen: Bevorzugen Sie POST, wenn der Partner es zulässt.

Sicherheit

  • Signieren Sie Ihre Anfragen (HMAC), sobald der Endpoint mehr als Testdaten verarbeitet.
  • Das Secret lässt sich jederzeit in der Konfiguration des Empfängers ändern (Rotation). Einmal gespeichert, wird es nie wieder angezeigt: Das Feld zeigt „•••••• gespeichert — zum Ersetzen eingeben“, und Entfernen löscht es (die Signatur wird dann nicht mehr geprüft).
  • Nutzlasten werden im Ausführungsverlauf im Klartext gespeichert — senden Sie keine Daten, die nur während der Übertragung verschlüsselt sein sollten.