Webhook HTTP

Le canal webhook est l'entrée générique pour brancher tout système qui sait faire un POST HTTP. C'est l'option à choisir quand aucun canal dédié n'existe pour votre source.

Quand l'utiliser

• Brancher un outil maison (ERP, application métier, gateway de paiement).
• Recevoir des événements d'une plateforme tierce qui propose des webhooks génériques.
• Déclencher un pipeline depuis un cron externe ou une CI.

Configuration

1. Dans l'éditeur du modèle, configurez le nœud Start avec un récepteur Webhook entrant.
2. betool génère une URL publique (https://platform.betool.ai/entries/webhook/<token>).
3. (Recommandé) Définissez un secret HMAC dans la config du récepteur.

Quand un secret est configuré, votre système doit signer le corps brut de chaque requête — HMAC-SHA256(secret, body), en hexadécimal — et passer la signature dans le header X-Webhook-Signature, sous la forme sha256=<hex> ou <hex> seul. Le nom du header et l'algorithme (sha256, sha384, sha512) sont configurables, par exemple pour suivre la convention X-Hub-Signature-256 de GitHub. Toute requête sans signature valide est alors refusée (401).

Format du payload

Vous envoyez n'importe quel JSON. betool ne contraint pas la structure. Le payload est exposé au pipeline sous webhook.payload (avec ses sous-clés) ; les en-têtes, la méthode et la query string sont aussi disponibles sous webhook.headers, webhook.method et webhook.query.

Le corps est lu selon son Content-Type : JSON parsé, formulaire (application/x-www-form-urlencoded) en dictionnaire, XML et text/* en texte brut, multipart/form-data en champs + fichiers joints (webhook.payload._files), tout autre type (PDF, image, archive…) enregistré comme fichier. Un corps compressé en gzip est décompressé. Taille maximale : 50 Mo (413 au-delà).

Exemple :

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"
  }'

Le pipeline peut alors brancher un agent qui lit webhook.payload.customer_email et webhook.payload.amount_cents directement.

Réponse

Deux modes de réponse (response_mode) : sync (par défaut) bloque jusqu'au résultat du pipeline et le renvoie dans la réponse ; ack renvoie immédiatement un 202 Accepted après avoir mis l'événement en file durable (le pipeline s'exécute ensuite, avec réessais) — à choisir pour les providers qui timeoutent tôt.

Appels GET (option)

Par défaut, seul POST est accepté : un GET reçoit 405. Pour un partenaire qui impose une consultation en GET ?action=…, cochez Accepter aussi GET (allow_get). La query string devient alors webhook.payload, sous la même forme qu'un POST de formulaire : le pipeline n'a pas à savoir quelle méthode a été utilisée. Un GET ne porte pas de body (refusé en 400) et n'est pas compatible avec la signature HMAC (refusé en 405 tant qu'un secret est renseigné). Un identifiant passé en query apparaît dans les journaux d'accès : préférez POST quand le partenaire le permet.

Sécurité

• Signez vos requêtes (HMAC) dès que l'endpoint traite autre chose que du test.
• Le secret se change à tout moment dans la config du récepteur (rotation).
• Les payloads sont stockés en clair dans l'historique d'exécutions — n'envoyez pas de données qui devraient être chiffrées en transit uniquement.