Comment utiliser les webhooks dans Postoria
Les webhooks de Postoria envoient les résultats des tentatives de publication terminées à un point de terminaison HTTPS public que vous contrôlez. Utilisez-les pour mettre à jour un outil de suivi interne, enregistrer les liens des publications dans votre CMS ou déclencher un processus de suivi à la fin d’une tentative de publication.
Les webhooks sont disponibles avec tous les forfaits, y compris Free. Ils fonctionnent pour les publications créées dans l’application Postoria et par les intégrations.
Avant de commencer
- Vous pouvez configurer une URL de webhook par profil. Elle reçoit les événements sélectionnés de tous les espaces de travail dont vous êtes propriétaire, y compris ceux que vous ne consultez pas actuellement.
- Les espaces de travail dont vous êtes uniquement membre de l’équipe ne sont pas inclus. C’est leur propriétaire qui gère leurs paramètres de webhook.
- Votre service récepteur doit accepter les requêtes HTTP
POSTà une URL HTTPS accessible publiquement. - L’URL peut contenir jusqu’à 2 048 caractères et ne doit inclure ni nom d’utilisateur, ni mot de passe, ni fragment d’URL tel que
#section. Postoria ne suit pas les redirections : saisissez donc l’URL de destination finale. - Vous n’avez pas besoin de clé d’API publique pour recevoir des webhooks. L’utilisation de l’API publique, du serveur MCP ou de l’intégration n8n de Postoria nécessite toujours un forfait Pro ou Agency.
Configurer votre webhook
- Ouvrez les Paramètres, trouvez la section Webhooks et cliquez sur Configurer.
- Saisissez l’adresse de votre service récepteur dans URL du webhook.
- Activez Activer les webhooks.
- Sous Événements à recevoir, sélectionnez Publication réussie, Échec de la publication, ou les deux. Au moins un événement doit être sélectionné lorsque les webhooks sont activés.
- Cliquez sur Enregistrer. La fenêtre se ferme et la section Webhooks affiche Activé ainsi que l’URL enregistrée.
- Dans la section Webhooks, trouvez Secret de signature. Sa valeur est masquée par défaut. Utilisez le bouton d’affichage ou de copie pour obtenir le secret et configurer la vérification des signatures dans votre service récepteur.
Gardez le secret de signature confidentiel. Il permet à votre service récepteur de vérifier qu’une requête a été signée par Postoria pour votre profil.
Une fois votre service récepteur prêt, publiez un contenu et consultez l’Historique des webhooks pour confirmer qu’il a bien reçu l’événement. L’activation des webhooks n’envoie pas d’événements pour les contenus dont la tentative de publication était déjà terminée.
Choisir les événements dont vous avez besoin
Un événement décrit une tentative de publication terminée pour un contenu. Postoria attend la fin de toutes les publications sélectionnées avant de communiquer le résultat global.
| Événement | Paramètre | Signification |
|---|---|---|
post.succeeded | Publication réussie | Toutes les publications sélectionnées se sont terminées avec succès. |
post.failed | Échec de la publication | La publication s’est terminée par un échec, y compris lorsque certaines publications ont réussi et d’autres ont échoué. |
Par exemple, si une publication réussit sur un compte et échoue sur un autre, l’événement est post.failed. Vérifiez les résultats individuels avant de décider ce qu’il faut réessayer : la publication réussie est déjà en ligne.
Ces événements concernent les tentatives de publication terminées. Ils ne signalent ni la disponibilité des médias, ni les mises à jour des statistiques, ni l’activité de la boîte de réception. Une demande de programmation rejetée ou une erreur empêchant le démarrage de la publication ne génère pas de webhook de résultat de publication. Prévoyez une vérification distincte pour les publications qui n’atteignent jamais de résultat final.
Lire le corps du message
Postoria envoie du JSON avec Content-Type: application/json; charset=utf-8. Cet exemple présente une publication avec un résultat réussi et un résultat en échec :
{
"id": "evt_7c7b19fd634441f3a0b460f2dc7e6812",
"type": "post.failed",
"occurred_at": "2026-11-15T12:00:00Z",
"workspace_id": 42,
"data": {
"post_id": 1234,
"results": [
{
"account_id": 101,
"link_to_post": "https://example.com/published-post",
"error": null
},
{
"account_id": 102,
"link_to_post": null,
"error": "The social account needs to be reconnected."
}
]
}
}
Les identifiants, le lien et l’erreur ci-dessus sont fournis à titre d’exemple.
ididentifie l’événement et reste identique d’une tentative de livraison à l’autre.typevautpost.succeededoupost.failed.occurred_atest l’heure UTC à laquelle Postoria a enregistré le résultat final de la publication, et non l’heure de la dernière tentative de livraison.workspace_ididentifie l’espace de travail. Utilisez-le pour acheminer les événements si votre service récepteur dessert plusieurs espaces de travail.data.post_idest l’identifiant de la publication dans Postoria.data.resultscontient les résultats de publication, avec un identifiant de compte social, un lien vers la publication lorsqu’il est disponible et une erreur, le cas échéant. Les champslink_to_posteterrorpeuvent tous deux valoirnull.
Les résultats utilisent les mêmes champs que les résultats de publication de l’API publique. Un compte peut apparaître plusieurs fois, par exemple lorsqu’une publication contient plusieurs Stories. Ne supposez pas qu’il existe exactement un résultat par compte.
Vérifier la signature
Chaque requête comporte trois en-têtes :
| En-tête | Valeur |
|---|---|
webhook-id | L’identifiant de l’événement, qui correspond à id dans le corps du message. |
webhook-timestamp | L’horodatage Unix en secondes de cette tentative de livraison. |
webhook-signature | v1, suivi d’une signature HMAC-SHA256 encodée en Base64. |
Pour vérifier une requête :
-
Lisez le corps brut de la requête avant d’analyser le JSON. L’analyser puis le sérialiser à nouveau peut modifier les octets et invalider la signature.
-
Retirez le préfixe
whsec_de votre secret de signature, puis décodez la valeur restante en Base64 pour obtenir la clé de signature. -
Assemblez l’en-tête
webhook-id, l’en-têtewebhook-timestampet le corps brut, dans cet ordre, en séparant chaque partie par un point :webhook-id.webhook-timestamp.raw-request-body -
Calculez le HMAC-SHA256 des octets UTF-8 de cette chaîne à l’aide de la clé de signature décodée, puis encodez le résultat en Base64.
-
Comparez votre résultat à la valeur qui suit
v1,danswebhook-signature, en utilisant une comparaison en temps constant. -
Vérifiez que l’horodatage signé respecte la tolérance d’écart d’horloge autorisée par votre service récepteur afin de limiter la réutilisation d’anciennes requêtes. Utilisez l’horodatage de l’en-tête pour cette vérification, car les nouvelles tentatives peuvent arriver bien après
occurred_at.
Rejetez les requêtes dont les en-têtes de signature sont absents ou invalides avant d’agir sur leur contenu. Utilisez webhook-id pour reconnaître les événements que votre service récepteur a déjà traités.
Répondre rapidement et gérer les nouvelles tentatives
Renvoyez une réponse HTTP 2xx dans un délai de 10 secondes pour accuser réception d’une livraison. En pratique, le service récepteur vérifie la requête, enregistre durablement l’événement et son identifiant, puis renvoie la réponse. Les traitements ultérieurs plus longs peuvent s’exécuter séparément après cet accusé de réception.
Postoria met la première livraison en file d’attente dès que le résultat de publication est enregistré. Les réponses autres que 2xx, les délais d’attente dépassés et les échecs de connexion déclenchent automatiquement de nouvelles tentatives. Les réponses de redirection comptent également comme des tentatives de livraison échouées.
Les nouvelles tentatives sont prévues 5, 15 et 30 minutes, puis 1, 3, 6, 12 et 24 heures après la première tentative. Ces délais sont calculés à partir de la première tentative, et non de la précédente. La livraison peut avoir lieu plus tard en cas de retard de traitement. Ce calendrier prévoit jusqu’à neuf tentatives, en comptant la première.
L’identifiant de l’événement et le corps JSON restent identiques d’une tentative à l’autre. Chaque tentative reçoit un nouvel horodatage d’envoi et une signature calculée pour cette tentative. Des livraisons en double sont possibles : assurez-vous que le traitement répété d’un même événement reste sans effet indésirable. Ne supposez pas que les différents événements arrivent dans l’ordre des publications.
Réessayer un webhook relance uniquement la livraison du résultat. Cela ne publie pas le contenu à nouveau.
Consulter l’historique des livraisons
Ouvrez Paramètres → Webhooks → Historique des webhooks, ou accédez directement à l’Historique des webhooks.
L’historique couvre les espaces de travail dont vous êtes propriétaire et est conservé pendant 30 jours. Chaque ligne affiche l’événement, l’identifiant de la publication, l’identifiant de l’espace de travail, l’état de livraison, le nombre de tentatives et le dernier statut HTTP. Développez une ligne pour afficher l’identifiant du message, les heures des tentatives, l’heure de livraison, l’erreur éventuelle et le corps JSON.
| État de livraison | Signification |
|---|---|
| En attente | Le message attend sa première livraison ou une nouvelle tentative. |
| Envoi en cours | Une tentative de livraison est en cours. |
| Livré | Votre service récepteur a renvoyé une réponse HTTP indiquant un succès. |
| Échec | Les tentatives de livraison se sont terminées sans réponse HTTP indiquant un succès. |
L’état de livraison et le résultat de la publication sont deux choses différentes. Un événement post.failed peut avoir l’état Livré : la publication a rencontré un échec, mais votre service récepteur a bien reçu cette information.
Rechargez la page pour voir les derniers états de livraison et utilisez Charger plus pour afficher les messages plus anciens. Si le chargement échoue, Réessayer relance le chargement de l’historique. Ces actions ne renvoient pas les webhooks.
Modifier l’URL ou désactiver les webhooks
Dans Paramètres → Webhooks, cliquez sur Configurer, modifiez l’URL ou désactivez Activer les webhooks, puis cliquez sur Enregistrer. La modification s’applique aux événements nouvellement créés.
Fermer la fenêtre de configuration sans cliquer sur Enregistrer annule vos modifications.
Lorsque les webhooks sont désactivés, la section Webhooks affiche Désactivé et masque l’URL enregistrée ainsi que le secret de signature. Cliquez sur Configurer pour modifier l’URL ou réactiver les webhooks.
Les événements déjà enregistrés conservent leur URL de destination d’origine et peuvent continuer à faire l’objet de nouvelles tentatives. Désactiver les webhooks n’annule pas ces livraisons en attente, et modifier l’URL ne les redirige pas vers la nouvelle adresse.
Résoudre les problèmes
- Les paramètres ne s’enregistrent pas : vérifiez que l’URL utilise HTTPS, qu’elle est publique, qu’elle ne contient ni identifiants intégrés ni fragment et qu’elle respecte la limite de longueur. Sélectionnez au moins un événement lorsque vous activez les webhooks.
- Aucun événement n’apparaît : vérifiez que les webhooks étaient activés avant la fin de la publication, que l’événement correspondant était sélectionné et que vous êtes propriétaire de l’espace de travail. Les erreurs survenant avant le démarrage de la publication ne sont pas couvertes par ces événements.
- La livraison échoue à répétition : consultez le dernier statut HTTP et l’erreur dans l’Historique des webhooks. Vérifiez que le point de terminaison est directement accessible, dispose d’un certificat HTTPS valide, accepte les requêtes
POSTet renvoie2xxen moins de 10 secondes. - La vérification de la signature échoue : utilisez le corps brut, décodez le secret en Base64 après avoir retiré
whsec_et incluez les valeurs exactes des en-têtes ainsi que les points de séparation dans la chaîne signée. - Le même événement arrive à nouveau : dédupliquez les événements par identifiant d’événement, et non par identifiant de publication. Une tentative de publication ultérieure pour la même publication peut produire un événement différent.