Notifier vos systèmes externes sur événements betool — exécution échouée, solde bas, validation humaine requise.

Webhooks sortants

Là où le canal webhook entrant reçoit des événements externes pour les traiter, les webhooks sortants font l'inverse : ils notifient vos systèmes quand un événement notable arrive dans betool.

Pourquoi

Vous avez probablement déjà :

Un système d'alerting (PagerDuty, Opsgenie, Slack).
Un outil ITSM (Jira, ServiceNow) pour gérer les tickets.
Un dashboard custom qui agrège votre état opérationnel.

Plutôt que de demander à ces systèmes de poller l'API betool, abonnez-les aux webhooks sortants : ils sont notifiés instantanément quand quelque chose se passe.

Configuration

Administration → Webhooks sortants → Nouvelle souscription.
Choisissez :
- URL cible — l'endpoint qui recevra les POSTs.
- Événements à écouter — voir liste ci-dessous.
- Secret HMAC — généré automatiquement, à utiliser côté votre récepteur pour vérifier les signatures.
(Optionnel) Filtres — restreindre aux exécutions d'un pipeline précis, à un niveau de gravité, etc.

Événements disponibles

Événement	Quand il se déclenche
`execution.failed`	Une exécution de pipeline a échoué
`execution.requires_human`	Un nœud `confirmation` attend une validation
`execution.cost_threshold`	Une exécution a dépassé un seuil de coût
`billing.low_balance`	Le solde de crédits passe sous le seuil configuré
`billing.out_of_credits`	Le solde est nul (refus pre-call actif)
`audit.cross_tenant_read`	Un agent externe a lu du contenu de cette organisation
`webhook.delivery_failed`	Un webhook sortant précédent a échoué 3 fois

Format d'un POST

POST /votre/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": "tri d'emails support",
    "failed_node": "agent: classifier",
    "error_kind": "llm_timeout",
    "error_message": "Provider responded after 30s timeout"
  }
}

Signature HMAC

Le header X-Betool-Signature contient sha256=<hmac> où hmac = HMAC-SHA256(secret, body). Vérifiez-le en réception pour vous assurer que la requête vient bien de betool :

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 & idempotence

Si votre endpoint répond 2xx, l'événement est marqué délivré.
Si non-2xx ou timeout, betool retry avec backoff exponentiel (1 min, 5 min, 30 min, 2 h, 12 h, 24 h — 6 tentatives max).
Après 6 échecs, l'événement est marqué dead-letter et un webhook.delivery_failed est émis (vers vos autres souscriptions actives).

Chaque POST porte un identifiant unique X-Betool-Delivery. Si votre endpoint reçoit deux fois la même delivery (cas réseau), traitez-la comme idempotente.

Sécurité

HTTPS obligatoire — les souscriptions HTTP simples sont refusées.
Secret rotatable — vous pouvez régénérer le secret à tout moment ; les vieux POSTs en transit utiliseront l'ancien jusqu'à expiration (5 min).
IP source — betool annonce ses IP sortantes sur status.betool.fr pour vous permettre de les autoriser au pare-feu.