Contrat de Callback Webhook

Ce document décrit uniquement ce que les utilisateurs callback reçoivent sur leur URL webhook.

Avant les callbacks : configurez l'endpoint webhook

Terminez d'abord cette configuration. La livraison des callbacks exige une URL webhook activée et un secret de signature valide.

Ouvrez Espace de travail -> Paramètres -> Webhooks.
Définissez votre URL de callback (HTTPS obligatoire). Cette URL reçoit tous les événements webhook.
Activez les webhooks et enregistrez les paramètres.
Copiez votre secret de signature (`whsec_...`) et stockez-le en sécurité. Vous avez besoin de ce secret pour vérifier `X-ContentKit-Signature`.
Envoyez un événement de test et confirmez que votre endpoint renvoie une réponse `2xx`.

Si l'URL callback est absente, si le webhook est désactivé, ou si votre endpoint renvoie un statut non-2xx, la livraison est traitée comme échouée.

Format de requête callback

Méthode

POST

En-têtes callback communs

Content-Type: application/json
X-ContentKit-Signature: t=<timestamp>,v1=<hmac_sha256>
X-ContentKit-Timestamp: <timestamp>

1) Callback de publication (`event: content.generated`)

Payload envoyé à l'utilisateur callback :

json

{
  "id": "evt_0f1d2c3b4a5e6f70",
  "event": "content.generated",
  "created": 1739865600,
  "data": {
    "job_id": "job_1739865600",
    "workspace_id": "workspace-id-or-unknown",
    "domain": "keyword-or-title",
    "status": "SUCCESS",
    "summary": {
      "total": 1,
      "processed": 1,
      "failed": 0
    },
    "result": {
      "id": "generated-article-id",
      "keyword": "best ai seo tools",
      "title": "Best AI SEO Tools in 2026",
      "slug": "best-ai-seo-tools-in-2026",
      "content": "<h1>...</h1>",
      "meta_description": "...",
      "json_ld": {}
    }
  }
}

`data.result` est l'objet brut de l'article généré.

L'utilisateur callback doit renvoyer un JSON `2xx` :

json

{
  "id": "external-post-id-123",
  "link": "https://client.example.com/blog/my-published-post"
}

`url` est accepté à la place de `link`.

2) Callback d'application des corrections (`event: fix.apply`)

Quand l'application des corrections utilise `integration_type=webhook`, le payload inclut :

json

{
  "id": "evt_214a2f9bdc294df1",
  "event": "fix.apply",
  "created": 1739866600,
  "data": {
    "target_url": "https://client.example.com/blog/my-post",
    "summary": {
      "total": 3,
      "processed": 3,
      "failed": 0
    },
    "fixes": [
      {
        "type": "meta",
        "location": "<head>",
        "action": "replace",
        "suggested_value": "<title>Updated Title</title>"
      },
      {
        "type": "schema",
        "location": "<head>",
        "action": "after",
        "suggested_value": "{\"@context\":\"https://schema.org\",\"@type\":\"Article\"}"
      },
      {
        "type": "image_alt",
        "location": "https://cdn.example.com/image.jpg",
        "action": "replace",
        "suggested_value": "Descriptive alt text"
      }
    ]
  }
}

L'utilisateur callback doit renvoyer un JSON `2xx` :

json

{
  "id": "external-fix-op-456",
  "link": "https://client.example.com/blog/my-post"
}

`url` est accepté à la place de `link`.

3) Formes exactes des corrections par source

Cette section définit la forme exacte de `data.fixes` selon l'endpoint source.

A) Si la source est `/apply-fix` (corrections manuelles)

`data.fixes` est transmis tel quel, exactement comme envoyé par le client.

Valeurs `type` prises en charge :

meta
schema
content_addition
content_replacement
structural
image_alt
faq

Champs typiques par correction :

obligatoire : `type`, `location`, `suggested_value`
optionnel : `action` (`before|after|replace`, valeur par défaut `after`)
optionnel : `current_value`, `reasoning`, `location_heading`

B) Si la source est `/apply-seo` (corrections générées)

`data.fixes` est généré avec ce mapping exact :

Meta title -> `type: "meta"`, `action: "replace"`, `suggested_value: "<title>...</title>"`
Meta description -> `type: "meta"`, `action: "replace"`, `suggested_value: "<meta name=\"description\" content=\"...\">"`
Schema item -> `type: "schema"`, `action: "after"`, `suggested_value: "<json string>"`
Alt text item -> `type: "image_alt"`, `action: "replace"`, `location: <image_url>`, `suggested_value: <alt_text>`
Bloc FAQ -> deux corrections sont générées : (1) `type: "content_addition"`, `action: "after"`, `suggested_value: "<div class=\"faq-section\">...</div>"`; (2) `type: "schema"`, `action: "after"`, `suggested_value: "<FAQPage json string>"`

Important : la FAQ issue de `/apply-seo` n'est pas envoyée avec `type: "faq"`; elle est envoyée comme `content_addition` plus `schema`.

4) Callback de statut de fin des corrections (`event: fix.generated`)

Après la fin du job de correction, un callback de statut peut être envoyé :

json

{
  "id": "evt_65e5d1e6c83d4040",
  "event": "fix.generated",
  "created": 1739866000,
  "data": {
    "job_id": "7c937cd0-a110-4f08-9a10-fdb03f1caef3",
    "workspace_id": "workspace-id",
    "domain": "https://example.com/page-being-fixed",
    "status": "SUCCESS",
    "summary": {
      "total": 1,
      "processed": 1,
      "failed": 0
    },
    "result": {
      "status": "success",
      "id": "cms-resource-id"
    }
  }
}

Règle d'échec de livraison

Si l'utilisateur callback renvoie un statut non-2xx, cette livraison est traitée comme échouée.