Webhooks

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. Nous n'avons aucun moyen de savoir ce qui se passe ensuite de votre côté. Nous ne pouvons pas détecter si votre code a réellement lu le JSON, mappé les champs correctement, ou mis l'article en ligne sur votre site.

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 sur votre blog alors que Sorank affiche « réussite », le problème vient presque toujours de la façon dont votre intégration capte et traite la charge utile, et non de la livraison elle-même.

Étape 1 : ouvrir l'intégration Webhook

1. Cliquez sur votre photo de profil dans le coin supérieur droit et sélectionnez Paramètres.
2. Ouvrez l'onglet Intégrations.
3. Faites défiler jusqu'à la carte Webhook et cliquez sur Connect your website.

É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.

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 émet deux types d'événements webhook. Les deux partagent la même enveloppe de premier niveau (event, delivery_id, timestamp, article), de sorte que votre intégration n'a qu'à se baser sur le champ event pour router la charge utile.

É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.

‍

{
  "event": "article.published",
  "delivery_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-05-21T10:30:45.123456Z",
  "article": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Best SEO Practices for 2025",
    "slug": "best-seo-practices-2025",
    "meta_description": "Discover the best SEO practices for 2025.",
    "focus_keyphrase": "seo practices",
    "content": "<h1>Best SEO Practices</h1><p>Article body content here...</p>",
    "featured_image": {
      "url": "https://storage.example.com/image.jpg",
      "alt": "Best SEO Practices for 2025",
      "placement": "hero"
    },
    "images": [
      {
        "url": "https://storage.example.com/image2.jpg",
        "alt": "SEO diagram",
        "placement": "body"
      }
    ],
    "word_count": 1500,
    "keyword": "seo practices",
    "language": "en-US"
  }
}

É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.

{

  "event": "webhook.test",

  "delivery_id": "550e8400-e29b-41d4-a716-446655440000",

  "timestamp": "2025-05-21T10:30:45.123456Z",

  "article": {

    "id": "00000000-0000-0000-0000-000000000000",

    "title": "Test Article - Webhook Connectivity Check",

    "slug": "test-article-webhook-check",

    "meta_description": "This is a test payload to verify webhook connectivity.",

    "focus_keyphrase": "webhook test",

    "content": "<h2>Test Article</h2><p>This is a test payload sent by SORANK to verify your webhook endpoint is working correctly.</p>",

    "images": [],

    "word_count": 20,

    "keyword": "webhook test",

    "language": "en-US"

  }

}

‍

Référence des champs

• event, type d'événement. Soit article.published soit webhook.test. Basez-vous sur ce champ pour router la charge utile.
• delivery_id, UUID unique pour chaque tentative de livraison. Stockez-le de votre côté pour dédupliquer les nouvelles tentatives et vous protéger contre les doubles publications.
• 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. Présent uniquement sur les événements article.published.
• 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 delivery_id comme clé d'idempotence pour éviter de publier deux fois le même article lors des nouvelles tentatives.
• 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. Lorsqu'un problème survient, il se situe presque toujours du côté réception. Voici les causes les plus fréquentes et comment les corriger.

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