Skip to content
User guide menu Webhooks Pages

Webhooks

Send audit, League rank and AI visibility events to your own systems with signed webhooks, and check the signature on each delivery.

Plans
Pro and up
Updated
On this page
  1. Add an endpoint
  2. Events
  3. Check the signature
  4. Deliveries

Webhooks send events from seoscore to your own systems as they happen, such as a CRM, an automation tool or a data warehouse. Each event is a signed JSON request to a URL you choose.

Add an endpoint

  1. Open Settings › Webhooks.
  2. Enter the Endpoint URL: an address on your server that accepts a JSON POST. Add a Description if you like.
  3. Tick the Events to send and press Add endpoint.
  4. Copy the endpoint's signing secret, which starts with whsec_, and press Send test to check your server answers.

Events

EventWhen it's sent
audit.completedA site's audit finished with a score.
rank.changedA site moved places on the League Table. Sent on every move, so you can set your own threshold.
ai_visibility.updatedA site's AI visibility score was worked out again.
webhook.pingYou pressed Send test.

Every request has the same shape: the event, when it occurred_at, and the details under data.

{
  "event": "audit.completed",
  "occurred_at": "2026-11-04T12:00:00+00:00",
  "team_id": 1,
  "data": {
    "audit_id": 7,
    "total_score": 84,
    "grade": "B",
    "categories": { "performance": 15, "content": 14 },
    "site": { "id": 3, "name": "Acme", "url": "https://acme.example.com", "league_rank": 4 }
  }
}

rank.changed adds previous_rank, current_rank and movement, which is positive when the site climbed. ai_visibility.updated adds ai_visibility_score and previous_score.

Check the signature

Each request carries these headers:

  • X-Webhook-Event: the event name.
  • X-Webhook-Delivery: a unique ID for this delivery.
  • X-Webhook-Signature: sha256= followed by an HMAC-SHA256 of the raw request body, keyed with your endpoint's signing secret.

Before you trust a request, work out the same HMAC from the raw body and compare the two with a constant-time comparison. In PHP:

$expected = 'sha256='.hash_hmac('sha256', $rawBody, $secret);

if (! hash_equals($expected, $request->header('X-Webhook-Signature'))) {
    abort(401);
}

Deliveries

Answer with any 2xx status to mark a delivery as delivered. The Webhooks page lists the latest deliveries with their status and your server's response code. A delivery that fails isn't sent again, so keep your endpoint quick and do any slow work after you've answered.

Try it on your own site. The Free plan needs no card.

Get my free score