> ## Documentation Index > Fetch the complete documentation index at: https://sorank.com/llms.txt > Use this file to discover all available pages before exploring further. # Webhooks > Doc Sorank - Webhooks ## Quand choisir la publication par webhook ? Le webhook relie Sorank à un site sur mesure ou à une automatisation qui sait recevoir un article et le publier. Il convient lorsque vous disposez déjà de ce système de publication ou que votre équipe peut le mettre en place. Le fonctionnement comporte trois étapes : Sorank prépare l’article, le transmet à votre intégration, puis votre intégration le publie sur votre site. Une fois ce parcours configuré, vous pouvez envoyer les articles depuis Sorank ou utiliser le calendrier pour automatiser leur génération et leur envoi. Avec le contrat de mise à jour décrit sur cette page, vous pouvez aussi envoyer une nouvelle version vers l’article existant. Par exemple, une modification préparée dans l’éditeur est envoyée à votre site lorsque vous cliquez sur **Envoyer la mise à jour de l’article**. Si vous souhaitez que Sorank gère aussi l’hébergement du blog, choisissez plutôt le [blog hébergé](/fr/documentation/host-your-blog-on-sorank). Si votre CMS possède un connecteur natif, utilisez le parcours présenté dans [publier et exporter](/fr/documentation/publier-et-exporter). ## Mettre à niveau un webhook existant Après la mise à jour de votre serveur, Sorank détecte automatiquement la prise en charge des mises à jour lors de la prochaine publication ou du prochain renvoi, si votre intégration est encore reconnue comme legacy. Sorank envoie `webhook.test` ; un échec de détection n’empêche pas la livraison habituelle. Pour déclencher la détection immédiatement, sans déconnecter votre webhook : 1. Ouvrez les paramètres de l’intégration webhook dans Sorank. 2. Gardez la même URL et le même secret. 3. Cliquez sur **Enregistrer**. Votre serveur doit répondre à `webhook.test` avec un statut HTTP 2xx et ce JSON à la racine : ```json theme={null} { "sorank_webhook_version": 2, "capabilities": ["article.published", "article.updated"] } ``` Cette déclaration active la mise à jour des articles publiés. `article_url` seule ne prouve pas que votre serveur accepte `article.updated`. La détection ne récupère pas rétroactivement les URL manquantes : chaque publication terminée doit renvoyer sa propre `article_url` selon le contrat ci-dessous. Vous n'avez pas d'intégration Sorank native pour votre CMS ? Le connecteur **Webhook** vous permet d'envoyer vos articles générés vers **n'importe quelle URL**, Zapier, Make, n8n ou un endpoint sur mesure sur votre propre site développé, afin que vous puissiez publier votre contenu là où vous en avez besoin. ## Comment ça fonctionne Lorsque vous publiez un article dans Sorank, nous envoyons une **requête POST** avec une charge utile JSON structurée vers l'URL que vous avez configurée. Votre endpoint ou votre outil d'automatisation peut alors traiter la charge utile et créer la publication sur votre blog, votre site sur mesure, ou tout autre outil qui accepte les requêtes HTTP entrantes. ## ⚠️ Important : le webhook envoie uniquement les données, c'est vous qui les publiez C'est la chose la plus importante à comprendre à propos du connecteur Webhook. De notre côté, Sorank regroupe **tout ce dont vous avez besoin dans le JSON** (titre, slug, corps HTML complet, méta-description, images, langue et plus encore) et l'envoie vers votre URL. Dès que ce JSON est envoyé avec succès, Sorank marque la livraison comme **réussie**. **Ce statut de « réussite » confirme une seule chose : les données ont quitté Sorank et votre endpoint les a acceptées.** Un simple accusé de réception historique ne confirme pas la publication. Avec le contrat version 2 ci-dessous, une réponse terminée avec `article_url` confirme immédiatement la publication dans Sorank ; votre code reste responsable de la publication effective dans votre CMS. Autrement dit, le webhook est **uniquement un mécanisme de livraison pour les données**. Le réceptionner, l'analyser et le publier sur votre CMS relève entièrement de votre responsabilité. Si l’article n’apparaît pas malgré une livraison réussie, vérifiez la réception, le traitement, la publication et la réponse retournée. Le statut de livraison seul ne permet pas d’identifier la cause. ## Étape 1 : ouvrir l'intégration Webhook 1. Dans le menu de gauche, ouvrez **Paramètres**, puis [Plateformes de publication](https://app.sorank.com/settings/integrations/publishing). 2. Faites défiler jusqu'à la carte **Webhook** et cliquez sur **Connect your website**. Webhooks: Étape 1 : ouvrir l'intégration Webhook ## Étape 2 : configurer votre endpoint 1. Collez votre URL de destination dans le champ **Webhook URL** (par exemple, un catch hook Zapier, un webhook Make, ou l'endpoint de votre propre serveur). 2. Si vous le souhaitez, ajoutez un **Secret token** si votre endpoint nécessite une authentification. Sorank l'inclura comme jeton `Bearer` dans l'en-tête `Authorization` afin que votre serveur puisse vérifier que l'appel provient de Sorank. 3. Cliquez sur **Test** pour envoyer une charge utile d'exemple (type d'événement `webhook.test`) et confirmer que votre endpoint répond correctement. 4. Cliquez sur **Save webhook** pour activer l'intégration. Webhooks: Étape 2 : configurer votre endpoint ## Détails de la requête HTTP Chaque webhook que Sorank envoie vers votre endpoint suit le même contrat HTTP. Voici ce que votre serveur recevra : * **Method:** `POST` * **Content-Type:** `application/json` * **User-Agent:** `SORANK-Webhook/1.0` * **Authorization:** `Bearer {webhook_secret}` (optionnel, envoyé uniquement si vous avez configuré un secret dans les paramètres de votre intégration) Utilisez l'en-tête `User-Agent` pour identifier le trafic Sorank dans vos journaux, et vérifiez l'en-tête `Authorization` de votre côté pour vous assurer que la requête provient de Sorank et non d'un appelant inconnu. ## Structure de la charge utile du webhook Sorank utilise trois événements avec la même enveloppe (`event`, `delivery_id`, `timestamp`, `article`). Une seule route **POST HTTPS** (par exemple `/sorank-webhook`) suffit : traitez chaque valeur de `event` sur cette route et vérifiez le jeton `Authorization` si vous avez configuré un secret. ### Version 2 : publier, mettre à jour et retourner l’URL Pour activer la mise à jour, votre route doit répondre à `webhook.test` sans créer de contenu, avec un HTTP 200 et ce JSON : ```json theme={null} { "sorank_webhook_version": 2, "capabilities": ["article.published", "article.updated"] } ``` Pour `article.published`, créez l’article et conservez l’association entre **`article.id`** et son identifiant dans votre CMS. Si cette association existe déjà, ne créez pas de doublon. Pour `article.updated`, retrouvez cette association et remplacez le contenu de l’article existant. Si l’article est introuvable, renvoyez une erreur, par exemple HTTP 404 : **une mise à jour ne doit jamais créer un nouvel article**. Après une publication réellement terminée, renvoyez HTTP 200 ou 201 avec : ```json theme={null} { "sorank_webhook_version": 2, "status": "published", "article_url": "https://example.com/blog/mon-article" } ``` Après une mise à jour terminée, utilisez `"status": "updated"` et l’URL publique actuelle. **Seule `article_url` est demandée, pas l’URL du sitemap.** Fournissez une URL HTTPS absolue sur le site associé au profil Sorank, pas celle de votre automatisation. La réponse doit être un objet JSON de moins de 16 Kio ; l’URL ne doit pas dépasser 2 048 caractères. Retournez dans `article_url` **l’URL HTTPS canonique exacte de l’article publié**, identique à sa balise ``. Respectez la présence ou l’absence de `www` et le slash final. Par exemple, si l’URL canonique est `https://example.com/blog/mon-article`, retournez-la sans `www`. Si elle est `https://www.example.com/blog/mon-article/`, conservez `www` et le slash final. Sorank utilise cette URL pour le suivi d’indexation dans Google Search Console. Ne retournez pas une autre URL simplement parce qu’elle redirige vers l’article ou affiche le même contenu. Une réponse version 2 avec `status: published` ou `status: updated` et une `article_url` valide enregistre immédiatement l’URL et affiche **Publié** avec son lien, même sans échange de backlinks. L’URL doit appartenir au site du profil. Ces réponses terminées n’attendent pas le vérificateur périodique. Seuls les reçus `accepted` ou HTTP 202 restent en attente de vérification. Les backlinks sont vérifiés séparément : confirmer la publication ne prouve pas la présence des liens et ne valide pas leurs crédits. Si une mise à jour échoue, la dernière URL vérifiée est conservée. Modifier le texte dans l’éditeur ne l’envoie pas automatiquement : cliquez sur **Envoyer la mise à jour**. ### Nouvelles tentatives et traitement asynchrone Utilisez l’en-tête `Idempotency-Key` pour dédupliquer la même opération sur le même instantané d’article et retourner la réponse mémorisée. `delivery_id` identifie seulement chaque tentative. Conservez aussi la correspondance `article.id` pour empêcher les doubles créations entre opérations différentes. L’en-tête `X-Sorank-Article-Revision` permet de refuser une ancienne version reçue après une version plus récente. Si le traitement n’est pas terminé, répondez HTTP 202 avec `"sorank_webhook_version": 2`, `"status": "accepted"` et, si connue, `"article_url"`. Un 202 ne confirme jamais la publication. Pour permettre à Sorank de vérifier ensuite cette opération asynchrone, ajoutez **uniquement après son application effective** cette balise dans le HTML public de l’article : ```html theme={null} ``` Remplacez la valeur par celle de l’en-tête `Idempotency-Key` reçu. Ne l’ajoutez pas dès la réception : l’ancienne page ne prouve pas la nouvelle mise à jour. Sans cette preuve, la vérification reste en attente puis expire. Si votre outil ne peut pas publier cette balise, terminez la publication avant de retourner la réponse 200/201. ### Migrer une intégration existante Une réponse 200 vide ou textuelle reste compatible avec la livraison historique, mais n’active pas les mises à jour. Adaptez votre route, cliquez sur **Test**, puis **Save webhook** : Sorank reteste les capacités côté serveur à l’enregistrement. Un changement d’URL ou de secret invalide les anciennes vérifications en cours. Pour mettre à jour des articles déjà publiés, reconstituez leur correspondance `article.id` côté CMS ; Sorank ne peut pas la deviner. ### Événement : article.published Déclenché chaque fois que vous publiez un article depuis Sorank. C'est l'événement que votre endpoint de production doit traiter pour créer la publication dans votre CMS ou déclencher votre flux d'automatisation. ‍ ### Événement : webhook.test Déclenché lorsque vous cliquez sur le bouton Test dans Sorank pour vérifier que votre endpoint est joignable. La charge utile utilise des valeurs fictives (id ne contient que des zéros, featured\_image est omis, images est vide) afin que votre intégration puisse l'ignorer en toute sécurité ou l'utiliser pour confirmer la connectivité sans créer de publication réelle. ‍ ### Référence des champs * **event**, `article.published`, `article.updated` ou `webhook.test`. Basez-vous sur ce champ pour router la charge utile. * **delivery\_id**, UUID unique pour tracer chaque tentative de livraison. Pour dédupliquer une opération, utilisez l’en-tête `Idempotency-Key`. * **timestamp**, horodatage ISO 8601 UTC du moment où l'événement a été émis. * **article.id**, identifiant unique de l'article dans Sorank. * **article.title**, le H1 / titre de l'article. * **article.slug**, slug adapté aux URL, en minuscules et avec des traits d'union. * **article.meta\_description**, méta-description SEO, prête à insérer dans votre balise ``. * **article.focus\_keyphrase**, expression-clé cible principale utilisée pour l'article. * **article.content**, corps complet de l'article en HTML, incluant les titres, paragraphes, listes et balises d'images en ligne. * **article.featured\_image**, objet image de couverture avec `url`, `alt` et `placement`. Peut être présent sur `article.published` et `article.updated`. * **article.images**, tableau d'images supplémentaires dans le corps. Chaque entrée comporte `url`, `alt` et `placement`. Peut être vide. * **article.word\_count**, nombre total de mots du corps de l'article. * **article.keyword**, identique à l'expression-clé cible, conservé comme champ distinct pour les intégrations rétrocompatibles. * **article.language**, balise de langue BCP 47 (par exemple `en-US`, `fr-FR`). ## Cas d'usage courants * **Zapier :** utilisez un déclencheur « Catch Hook » pour transférer les articles vers des milliers d'applications telles que WordPress, Notion, Airtable ou Google Sheets. * **Make :** utilisez un module Webhooks pour créer des automatisations de publication personnalisées en plusieurs étapes. * **n8n :** reliez un nœud Webhook à un flux qui crée la publication dans votre CMS headless ou votre back-office. * **Backend sur mesure :** envoyez les articles directement vers votre propre API pour publier sur un site développé à la main, un CMS headless tel que Sanity ou Strapi, ou tout outil interne. ## Conseils * Cliquez toujours sur **Test** avant d'enregistrer pour confirmer que votre endpoint accepte la requête et renvoie une réponse 2xx. * Basez-vous sur le champ `event` côté serveur afin que les appels `webhook.test` ne créent jamais de publications réelles. * Utilisez `Idempotency-Key` pour dédupliquer une opération et `article.id` pour retrouver le même article dans votre CMS. * Gardez votre **Secret token** privé, vérifiez l'en-tête `Authorization` à chaque requête, et faites tourner le secret régulièrement. * Utilisez un endpoint HTTPS pour garder les données des articles sécurisées pendant le transit. * Une fois connecté, chaque article publié dans Sorank sera automatiquement envoyé vers votre URL de webhook. ## 🔄 Pourquoi vos articles peuvent ne pas apparaître (causes d'échec) Comme le webhook ne fait que livrer les données, une « réussite » dans Sorank ne garantit pas que l'article est en ligne sur votre site. Vérifiez chaque étape pour localiser le blocage. Voici les points à examiner. ### Causes du côté de votre intégration * **Votre clé d'API CMS est en lecture seule au lieu d'être en lecture et écriture**, c'est l'un des problèmes les plus fréquents. Si les identifiants que votre code utilise pour écrire dans votre CMS (Sanity, Strapi, Contentful, ou tout backend headless) ne disposent que de permissions *de consultation / lecture*, votre endpoint recevra le JSON mais échouera silencieusement à créer la publication. Générez une clé avec un accès en **écriture** et mettez-la à jour dans votre intégration. * **Votre code reçoit le JSON mais ne l'envoie jamais vers votre CMS**, recevoir la charge utile ne représente que la moitié du travail. Assurez-vous que votre endpoint mappe réellement les champs Sorank et crée la publication dans votre CMS ou votre base de données. Journalisez la charge utile entrante et confirmez que votre appel de publication s'exécute et réussit. * **Le mappage des champs est incorrect**, si votre code attend des noms de champs différents de ceux présents dans la charge utile, la publication peut être créée vide ou rejetée. Vérifiez bien que vous lisez `article.title`, `article.slug`, `article.content`, etc., exactement comme documenté ci-dessus. * **Votre endpoint renvoie un 2xx mais lève une erreur ensuite**, si vous accusez réception de la requête avant de la traiter de manière asynchrone, un échec ultérieur dans votre logique de publication ne sera pas visible pour Sorank. Consultez vos propres journaux serveur pour les détecter. ### Causes du côté livraison * **Votre endpoint de webhook ne répond plus** (serveur hors ligne), remettez votre serveur en ligne et vérifiez que l'URL répond normalement. * **L'URL du webhook a changé mais n'a pas été mise à jour dans Sorank**, mettez à jour l'URL dans les paramètres d'intégration de Sorank. * **Vous avez régénéré votre secret de webhook de votre côté**, mettez à jour le secret dans Sorank pour qu'il corresponde à celui que votre serveur attend désormais dans l'en-tête `Authorization`. * **Votre endpoint renvoie une erreur que Sorank ne peut pas interpréter**, consultez vos journaux serveur pour identifier le problème, puis corrigez-le du côté de votre webhook. * **Un pare-feu sur votre serveur bloque nos requêtes**, ajoutez les adresses IP de Sorank à la liste autorisée de votre pare-feu, ou autorisez le User-Agent `SORANK-Webhook/1.0`. * **Votre endpoint met plus de 30 secondes à répondre**, optimisez votre endpoint pour qu'il réponde plus vite, ou accusez réception de la requête immédiatement et traitez-la de manière asynchrone. Lorsque Sorank ne parvient pas à livrer un article à votre endpoint, votre planificateur est automatiquement mis en pause et vous recevez un e-mail. Dès que vous corrigez le problème et reconnectez votre webhook dans Sorank, votre planificateur reprend de lui-même. Votre article est déjà généré et stocké en toute sécurité, rien n'est perdu. ## 🚀 Vous n'êtes pas développeur ? Hébergez plutôt votre blog sur Sorank Le webhook vous oblige à écrire et à maintenir du code qui capte le JSON et le publie sur votre site. Si vous avez construit votre site avec un outil no-code ou un outil d'IA, comme **Lovable**, **Base44**, **Cursor** ou **Claude Code**, et que vous n'êtes pas en mesure de développer et d'héberger un endpoint qui capte le webhook et publie l'article, il existe une voie bien plus simple. Nous avons créé une solution qui vous permet d'**héberger automatiquement votre blog sur votre propre sous-domaine, directement sur Sorank**. Pas de code, pas d'endpoint à maintenir, pas de webhook à capter. Découvrez comment cela fonctionne ici : [Hébergez votre blog sur Sorank](/fr/documentation/host-your-blog-on-sorank). ## Vous cherchez plutôt une intégration native ? Si votre plateforme est prise en charge, un connecteur direct est plus simple que le webhook. Consultez nos guides pour [Webflow](/fr/documentation/connecter-webflow), [Shopify](/fr/documentation/connecter-shopify), [WordPress.org](/fr/documentation/connecter-wordpress-org), [WordPress.com](/fr/documentation/connecter-wordpress-com), [Wix](/fr/documentation/connecter-wix) et [HubSpot](/fr/documentation/utiliser-hubspot-avec-sorank). ### Le problème persiste après vérification ? Si vous avez vérifié les points ci-dessus et que la publication échoue toujours, répondez directement à l'e-mail que vous avez reçu : notre équipe examinera ce qui se passe sur votre compte. Vos articles restent générés et stockés en toute sécurité dans Sorank. Dès que la connexion est rétablie, votre planificateur reprend automatiquement là où il s'était arrêté.