Automatisation

Webhooks

Prévenez un autre système quand une publication de Sofia est en ligne ou échoue : webhooks signés enregistrés avec l’API, avec relances.

Un webhook est un appel HTTP que Sofia déclenche quand une publication est en ligne ou échoue. Servez-vous-en pour reprendre le contenu dans un tableur, prévenir un outil de messagerie, ou lancer un scénario dans Zapier ou n8n.

En ajouter un

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.

Construire le récepteur

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.

Quand un webhook ne se déclenche plus

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.

Cette page vous a-t-elle aidé ?