Webhooks

Webhooks push events to your server in real time, so you can react to ranking changes, completed imports and generated briefs without polling.

Register an endpoint

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"]
  }'

Event payload

Every delivery is a JSON body with a type and a data object:

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

Verifying deliveries

Each request is signed with an X-SEO-Insight-Signature header: an HMAC of the raw body using your endpoint's signing secret. Compute the same HMAC on your side and compare before trusting the payload.

Always verify the signature, and respond with a 2xx quickly: heavy work should happen asynchronously so deliveries aren't retried.