Webhooks

Les webhooks sont la manière dont Tale et le reste de ta stack se parlent en asynchrone. Deux directions existent : entrant — ton système POST sur un déclencheur de workflow Tale pour tirer une exécution — et sortant — Tale POST sur ton URL quand quelque chose qui l'intéresse arrive. Les deux moitiés partagent le modèle d'auth (un bearer token), le schéma de signature (HMAC-SHA256 sur le body) et la politique de retraitement (backoff exponentiel avec jitter).

Lis ceci quand tu câbles une intégration qui doit réagir à des événements dans une des directions. Reviens-y quand un webhook tire mais que le récepteur ne le voit pas, ou quand les retries ne se comportent pas comme tu l'attendais.

Un webhook sortant mis en pratique

Quand un événement que Tale surveille survient — une exécution de workflow se termine, un agent finit une réponse, une écriture de document s'achève — Tale POST l'événement sur ton URL configurée :

POST https://your-host.example.com/webhooks/tale
Content-Type: application/json
X-Tale-Event: workflow.execution.completed
X-Tale-Signature: sha256=<hex>
X-Tale-Delivery: <uuid>
X-Tale-Timestamp: 1717000000

{
  "event": "workflow.execution.completed",
  "data": { "workflowId": "...", "executionId": "...", "status": "succeeded", ... }
}

Vérifie la signature avant de faire confiance au body : HMAC-SHA256 sur le body brut avec le secret par endpoint, encodé en hex. Compare en temps constant. Rejette toute requête plus vieille que cinq minutes en comparant X-Tale-Timestamp à ton horloge.

Un déclencheur entrant mis en pratique

Quand ton système doit tirer un workflow Tale, POST sur l'URL du déclencheur du workflow :

curl -sS https://your-host.example.com/api/v1/workflows/triggers/<trigger-name> \
  -H "Authorization: Bearer $TALE_TRIGGER_KEY" \
  -H "Idempotency-Key: order-12345" \
  -H "Content-Type: application/json" \
  -d '{ "orderId": "12345", "amount": 199.0 }'

La clé de déclencheur est une clé API portée sur le déclencheur webhook, émise aux côtés du déclencheur dans l'éditeur de workflow. Le body devient l'entrée de la première étape du workflow. La réponse est du JSON avec un executionId que tu peux citer en vérifiant l'exécution.

Signer et vérifier

Sortant : le secret de signature par endpoint est affiché une fois quand tu ajoutes l'endpoint sous Paramètres > Intégrations ou dans le panneau de déclencheur webhook de l'éditeur de workflow. Tale signe chaque body en HMAC-SHA256 avec ce secret ; la vérification est une comparaison de chaînes en temps constant.

Entrant : il n'y a pas de signature — le bearer token est l'auth. Si tu ne peux pas garder le token secret, n'expose pas l'URL du déclencheur.

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)

Idempotence

Entrant : passe Idempotency-Key à chaque appel de déclencheur. Tale stocke la clé contre l'exécution résultante pendant 24 heures ; un retry avec la même clé renvoie le même ID d'exécution sans retirer le workflow.

Sortant : chaque livraison porte un UUID X-Tale-Delivery unique. Utilise-le pour dédupliquer de ton côté — Tale retraite sur les réponses non-2xx, et le même UUID de livraison apparaîtra à chaque retry jusqu'à ce que le récepteur acquitte.

Retraitements

Les retraitements sortants suivent un backoff exponentiel avec jitter, plafonnés à 24 heures de tentatives. Le calendrier :

• Retry immédiat sur un 5xx ou un timeout.
• 30 s, 1 m, 5 m, 30 m, 2 h, 8 h, 24 h après le premier échec.
• Après 24 h sans 2xx, la livraison est marquée comme échouée ; le journal d'audit l'enregistre.

Les retraitements entrants sont la responsabilité de l'appelant — la réponse de Tale indique le succès ou l'échec du déclencheur, pas des étapes du workflow. Si tu veux retraiter, utilise une clé d'idempotence stable.

Où cela s'inscrit

Les webhooks sont la couture entre Tale et les systèmes externes des deux côtés. La référence API couvre la moitié synchrone — les endpoints que tu appelles quand tu veux une valeur en retour immédiate. La référence Déclencheurs couvre le côté workflow des webhooks entrants — la configuration qui transforme un POST en une exécution de workflow.