Webhooks

• 1. Donnez-lui une adresse. Une adresse https publique où Sofia enverra l’événement.
• 2. Choisissez les événements. post.published et post.failed.
• 3. Enregistrez-le. POST /v1/webhooks : le secret de signature (whsec_…) n’est affiché que dans cette réponse.
• 4. Envoyez un test. POST /v1/webhooks/{id}/test envoie un événement webhook.test, signé comme les autres.

La requête complète est détaillée dans l’onglet API : Enregistrer un webhook. Seules les publications créées par votre application sont annoncées.

Envoyez toujours un test d’abord et gardez le corps reçu : c’est le contrat, plus fiable que n’importe quelle description. Sofia envoie chaque événement en POST au format JSON { id, type, createdAt, data }, avec les en-têtes Sofia-Event-Id, Sofia-Event-Type et Sofia-Signature.

• Vérifiez la signature. Sofia-Signature vaut t=<unix time>,v1=<hex>, où v1 est le HMAC-SHA256 de <t>.<raw body> avec votre secret. Calculez-le sur le corps brut et refusez un horodatage ancien.
• Répondez `2xx` vite, puis faites le travail ensuite : un point d’arrivée lent ne se distingue pas d’un point d’arrivée en panne.
• Soyez idempotent. Un même événement peut arriver deux fois : dédupliquez sur Sofia-Event-Id.

L’adresse n’est pas joignable

Sofia appelle depuis ses serveurs : l’adresse doit être un https public. Une redirection n’est jamais suivie, et 10 secondes sans réponse comptent comme un échec.

L’adresse renvoie une erreur

Toute réponse autre que 2xx déclenche une nouvelle tentative après 1 minute, 5 minutes, 30 minutes et 2 heures, jusqu’à 5 tentatives. Regardez d’abord vos propres journaux, puis reproduisez avec POST /v1/webhooks/{id}/test.

La publication n’a pas été créée par votre application

Un webhook n’annonce que les publications créées par votre application ; une publication créée dans l’interface ne le déclenche pas.

Un webhook dit quand Sofia a agi. Pour faire agir Sofia, utilisez Sofia API, la CLI sofia ou le serveur MCP (onglets API et Agents), ou Intégrations tierces.