betool betool

Dokumentation

HTTP-Webhook

Generischer Empfang signierter HTTP-Ereignisse von beliebigen Systemen.

HTTP-Webhook

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 Webhooks bietet (Stripe, Shopify, SendGrid …).
  • Eine Pipeline aus einem externen Cron-Job oder einer CI-Pipeline auslösen.

Konfiguration

  1. Administration → Webhooks → Neuer Eingang.
  2. Wählen Sie die Ziel-Pipeline.
  3. betool generiert eine öffentliche URL (https://platform.betool.ai/entries/webhook/<id>) und ein HMAC-Secret.

Das Secret dient dazu, jede Nutzlast zu signieren: Ihr System muss HMAC-SHA256(secret, body) berechnen und im Header X-Betool-Signature übergeben. Anfragen ohne gültige Signatur werden abgelehnt.

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.

Beispiel:

curl -X POST https://platform.betool.ai/entries/webhook/abc123 \
  -H "Content-Type: application/json" \
  -H "X-Betool-Signature: $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

Standardmäßig gibt die HTTP-Antwort sofort 202 Accepted zurück (Pipeline im Hintergrund gestartet). Wenn Sie auf das Pipeline-Ergebnis warten müssen, konfigurieren Sie den Webhook im synchronen Modus — die Anfrage blockiert, bis die Pipeline abgeschlossen ist (30 s Timeout).

Sicherheit

  • Signieren Sie Ihre Anfragen immer (HMAC).
  • Das Secret kann über den Adminbereich neu generiert werden (Rotation).
  • Nutzlasten werden im Ausführungsverlauf im Klartext gespeichert — senden Sie keine Daten, die nur während der Übertragung verschlüsselt sein sollten.