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
Ajoutewebhook_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 terminales —completed
ou failed. Les jobs qui sont cancelled n’émettent pas de webhook.
Payload
Le corps de la requête est du JSON. L’objetdata a la même forme que celle que tu
obtiens du endpoint de statut GET du job.
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,.
Vérifier la signature
Tonwebhook_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.|now − webhook-timestamp| > 300 secondes.
Réessais et règles de livraison
- Un succès est toute réponse
2xxrenvoyée dans un timeout de 10 secondes (timeout de connexion 5s). Un3xxest traité comme un échec — Samsa ne suit pas les redirections. - En cas d’échec, Samsa réessaie avec la tentative initiale plus 5 réessais —
6 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.

