Benachrichtigen Sie Ihre externen Systeme bei betool-Ereignissen — fehlgeschlagene Ausführung, niedriges Guthaben, erforderliche menschliche Validierung.

Ausgehende Webhooks

Während der eingehende Webhook-Kanal externe Ereignisse zur Verarbeitung empfängt, tun ausgehende Webhooks das Gegenteil: Sie benachrichtigen Ihre Systeme, wenn in betool ein nennenswertes Ereignis eintritt.

Warum

Sie haben wahrscheinlich bereits:

Ein Alerting-System (PagerDuty, Opsgenie, Slack).
Ein ITSM-Tool (Jira, ServiceNow) zur Verwaltung von Tickets.
Ein individuelles Dashboard, das Ihren operativen Status aggregiert.

Anstatt diese Systeme die betool-API abfragen zu lassen, abonnieren Sie sie für ausgehende Webhooks: Sie werden sofort benachrichtigt, wenn etwas passiert.

Konfiguration

Administration → Ausgehende Webhooks → Neues Abonnement.
Wählen Sie:
- Ziel-URL — der Endpunkt, der die POSTs empfängt.
- Ereignisse, auf die reagiert werden soll — siehe die Liste unten.
- HMAC-Geheimnis — automatisch generiert; verwenden Sie es auf Ihrer Empfängerseite, um Signaturen zu verifizieren.
(Optional) Filter — beschränken Sie auf Ausführungen einer bestimmten Pipeline, auf einen Schweregrad usw.

Verfügbare Ereignisse

Ereignis	Wann es ausgelöst wird
`execution.failed`	Eine Pipeline-Ausführung ist fehlgeschlagen
`execution.requires_human`	Ein `confirmation`-Knoten wartet auf Validierung
`execution.cost_threshold`	Eine Ausführung hat einen Kostenschwellenwert überschritten
`billing.low_balance`	Das Guthaben ist unter den konfigurierten Schwellenwert gefallen
`billing.out_of_credits`	Das Guthaben ist null (Verweigerungen vor dem Aufruf sind aktiv)
`audit.cross_tenant_read`	Ein externer Agent hat Inhalte dieser Organisation gelesen
`webhook.delivery_failed`	Ein vorheriger ausgehender Webhook ist 3-mal fehlgeschlagen

POST-Format

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-Betool-Event: execution.failed
X-Betool-Signature: sha256=...
X-Betool-Delivery: dlv_01HXYZ...

{
  "event": "execution.failed",
  "delivered_at": "2026-05-24T10:42:13Z",
  "org_id": "org_...",
  "data": {
    "execution_id": "exec_...",
    "pipeline_id": "pip_...",
    "pipeline_name": "support email triage",
    "failed_node": "agent: classifier",
    "error_kind": "llm_timeout",
    "error_message": "Provider responded after 30s timeout"
  }
}

HMAC-Signatur

Der Header X-Betool-Signature enthält sha256=<hmac>, wobei hmac = HMAC-SHA256(secret, body). Verifizieren Sie ihn beim Empfang, um sicherzustellen, dass die Anfrage tatsächlich von betool stammt:

import hmac, hashlib

def verify(body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(),
        body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Retry & Idempotenz

Antwortet Ihr Endpunkt mit 2xx, wird das Ereignis als zugestellt markiert.
Bei einer Antwort ungleich 2xx oder einem Timeout wiederholt betool den Versuch mit exponentiellem Backoff (1 Min., 5 Min., 30 Min., 2 Std., 12 Std., 24 Std. — maximal 6 Versuche).
Nach 6 Fehlschlägen wird das Ereignis als Dead-Letter markiert und ein webhook.delivery_failed ausgegeben (an Ihre anderen aktiven Abonnements).

Jeder POST trägt eine eindeutige Kennung X-Betool-Delivery. Empfängt Ihr Endpunkt dieselbe Zustellung zweimal (Netzwerk-Grenzfall), behandeln Sie sie idempotent.

Sicherheit

HTTPS erforderlich — Abonnements über einfaches HTTP werden abgelehnt.
Rotierbares Geheimnis — Sie können das Geheimnis jederzeit neu generieren; laufende POSTs, die das alte Geheimnis verwenden, werden bis zum Ablauf (5 Min.) weiterhin akzeptiert.
Quell-IPs — betool veröffentlicht seine ausgehenden IPs auf status.betool.fr, damit Sie sie in Ihrer Firewall auf eine Positivliste setzen können.