Skip to main content

​
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é. Si votre CMS possède un connecteur natif, utilisez le parcours présenté dans 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 :
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.
  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 :
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 :
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 <link rel="canonical">. 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 :
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 <meta name="description">.
  • 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.

​
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, Shopify, WordPress.org, WordPress.com, Wix et HubSpot.

​
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é.