Webhooks de l'API Surfer

Les webhooks permettent à Surfer de notifier votre serveur au moment où quelque chose se produit, comme la fin du traitement d'un Éditeur de contenu ou la fin d'une exécution d'Auto-optimisation, afin que vous n'ayez pas à sonder les mises à jour en continu.

Configuration des webhooks

La configuration des webhooks est gérée par l'équipe d'assistance. Pour commencer :

1. Configurez un point de terminaison HTTPS de votre côté, qui accepte les requêtes POST et répond avec HTTP 200 OK.

2. Contactez l'assistance Surfer par email ou chat en direct et partagez l'URL.

3. L'assistance enregistrera le point de terminaison et vous enverra une Verification-Key à utiliser pour authentifier les requêtes entrantes de votre côté.

Une fois configuré, Surfer enverra une requête POST à votre point de terminaison chaque fois qu'un événement pris en charge se déclenche. Chaque requête inclut un en-tête Verification-Key et un corps JSON.

Structure de la charge utile du webhook

Tous les événements webhook suivent la même enveloppe :

{
  "id": 123,
  "type": "event.name.here",
  "timestamp": "2024-06-01T12:00:00Z",
  "payload": {
    ...
  }
}

Événements pris en charge

Initialisation de l'Éditeur de contenu

Se déclenche après que POST /api/v2/workspaces/{workspace_id}/content_editors termine le traitement.

Champs de charge utile : draft_id (entier), permalink_hash (chaîne de caractères)

{
  "id": 123,
  "type": "content_editor.initialization.completed",
  "timestamp": "2024-06-01T12:00:00Z",
  "payload": {
    "draft_id": 5632898,
    "permalink_hash": "kKi7n3pkRk7Gw5cxKDiBAbCAybnDTt2z"
  }
}

Recalcul du Content Score

Se déclenche après que vous avez mis à jour le contenu d'un Éditeur de contenu via l'API.

Champs de charge utile : draft_id (entier), permalink_hash (chaîne de caractères), content_score (entier)

{
  "id": 124,
  "type": "content_editor.content_score.recalculated",
  "timestamp": "2024-06-01T12:05:00Z",
  "payload": {
    "draft_id": 5632898,
    "permalink_hash": "kKi7n3pkRk7Gw5cxKDiBAbCAybnDTt2z",
    "content_score": 74
  }
}

Génération d'articles par IA

Se déclenche pendant et après la génération d'articles Surfer AI.

Champs de charge utile : draft_id (entier), permalink_hash (chaîne de caractères)

Auto-optimisation

Se déclenche après la fin, l'échec ou l'annulation d'une exécution d'Auto-optimisation.

Champs de charge utile : job_id (entier), draft_id (entier), result (chaîne de caractères, uniquement sur completed)

Le champ result vaut soit "optimized" (le contenu a été modifié), soit "nothing_to_optimize" (le contenu était déjà bien optimisé).

{
  "id": 125,
  "type": "content_editor.auto_optimize.completed",
  "timestamp": "2024-06-01T12:10:00Z",
  "payload": {
    "job_id": 456,
    "draft_id": 5632898,
    "result": "optimized"
  }
}

Score SEO (V2 uniquement)

Score de recherche IA (V2 uniquement)

Génération de plan (V2 uniquement)

Chargement des concurrents (V2 uniquement)

Référence complète des événements

Ressources supplémentaires :

Introduction à l'API Surfer

Documentation de l'API Surfer (v1)

Documentation de l'API Surfer (v2)

Exemples d'utilisation de l'API Surfer