export const metadata = {
  title: "Webhooks : Docs SEO Insight",
  description:
    "Recevez des événements en temps réel quand des mots-clés bougent, que des briefs sont générés ou que des imports se terminent.",
};

# Webhooks

Les webhooks poussent des événements vers votre serveur en temps réel, pour que
vous réagissiez aux changements de classement, aux imports terminés et aux briefs
générés sans interrogation (polling).

## Enregistrer un endpoint

```bash
curl https://api.seoinsight.app/v1/webhooks \
  -H "Authorization: Bearer $SEO_INSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/seo-insight",
    "events": ["keyword.quick_win", "brief.created"]
  }'
```

## Charge utile de l'événement

Chaque livraison est un corps JSON avec un `type` et un objet `data` :

```json
{
  "type": "keyword.quick_win",
  "data": { "keyword": "seo mcp server", "position": 14, "volume": 320 }
}
```

## Vérifier les livraisons

Chaque requête est signée avec un en-tête `X-SEO-Insight-Signature` : un HMAC du
corps brut utilisant le secret de signature de votre endpoint. Calculez le même
HMAC de votre côté et comparez avant de faire confiance à la charge utile.

> Vérifiez toujours la signature, et répondez rapidement par un `2xx` : les
> traitements lourds doivent se faire de manière asynchrone pour que les
> livraisons ne soient pas réessayées.