Skip to main content
Chaque endpoint de génération est asynchrone. Plutôt que d’interroger le endpoint GET, tu peux passer un webhook_url et Samsa y enverra un POST avec un événement signé dès l’instant où le job atteint un statut terminal.

Demander un webhook

Ajoute webhook_url à n’importe quelle requête de génération. C’est par requête — des jobs différents peuvent viser des URLs différentes.
Les webhooks sont une commodité, pas la source de vérité. Si toutes les tentatives de livraison échouent, le résultat du job reste disponible depuis son endpoint GET. Interroge en secours pour tout ce qui est critique.

Événements

Les webhooks ne se déclenchent que sur les transitions terminalescompleted ou failed. Les jobs qui sont cancelled n’émettent pas de webhook.

Payload

Le corps de la requête est du JSON. L’objet data a la même forme que celle que tu obtiens du endpoint de statut GET du job.
Pour un événement failed, status vaut "failed" et data porte un objet error utilisant la même forme interne que l’enveloppe d’erreur.

Headers de signature

Chaque livraison porte trois headers :
Le schéma est compatible Svix : HMAC-SHA256 sur {webhook-id}.{webhook-timestamp}.{raw-body}, encodé en base64, préfixé par v1,.
Signe et vérifie sur les octets bruts de la requête exactement tels que reçus — jamais une copie re-sérialisée. Re-sérialiser (réordonner les clés, changer les espaces) change les octets et casse la signature.

Vérifier la signature

Ton webhook_secret par clé vit dans l’app sous Settings → API Keys (chaque clé a son propre secret ; fais-le tourner indépendamment de la clé). Les snippets ci-dessous sont vérifiés contre un vecteur de test fixe — exécute-les tels quels et ils renvoient true, pour que tu puisses confirmer que ton implémentation reproduit la signature octet par octet avant de câbler un vrai secret.
Le corps du vecteur de test est une chaîne de référence fixe, donc ses octets exacts ne changent jamais et la signature reste reproductible — ce n’est intentionnellement pas le payload de l’événement live montré ci-dessus. La vérification de signature tourne toujours sur les octets bruts exacts que tu reçois, quelle que soit leur forme, donc c’est purement un auto-test pour ton vérificateur. De même, webhook-id est une chaîne opaque, stable par événement — traite-la comme un token, ne l’analyse jamais.
En production, applique toujours aussi la fenêtre de timestamp : rejette la livraison si |now − webhook-timestamp| > 300 secondes.

Réessais et règles de livraison

  • Un succès est toute réponse 2xx renvoyée dans un timeout de 10 secondes (timeout de connexion 5s). Un 3xx est traité comme un échec — Samsa ne suit pas les redirections.
  • En cas d’échec, Samsa réessaie avec la tentative initiale plus 5 réessais6 tentatives de livraison au total — en ralentissant 5s → 30s → 2m → 15m → 1h.
  • Après la dernière tentative, la livraison est abandonnée (et loggée). Le résultat du job reste interrogeable depuis son endpoint GET.
  • Les endpoints doivent être en HTTPS. Réponds rapidement (2xx) et fais le traitement lourd de façon asynchrone pour ne jamais dépasser la fenêtre de 10 secondes.
Utilise le webhook-id stable pour rendre ton handler idempotent. Une livraison réessayée réutilise le même webhook-id, donc tu peux ignorer en toute sécurité un événement que tu as déjà traité.