Skip to content

Completion events

Signed webhooks when a Tracker scan, Page Audit or Site Audit finishes, shared with the MCP server's events.

Get a signed webhook when work finishes instead of polling. These are the same events and subscriptions as the hosted MCP server’s events: one credential sees one set of subscriptions on either surface.

Event Scope Fires when
tracker.scan.completed reporter:read A Tracker scan completes with a saved report. Partial and failed scans do not fire.
page_audit.completed page_audit:read A Page Audit completes with a saved report.
site_audit.completed site-auditor:read A Site Audit completes with a saved report.

GET /events lists the events your credential can subscribe to.

POST /events/subscriptions
Content-Type: application/json
{
"name": "page_audit.completed",
"client_id": "CLIENT_UUID",
"project_id": "OPTIONAL_AUDIT_OR_PROJECT_ID",
"url": "https://hooks.example.com/rankability",
"secret": "whsec_BASE64_24_TO_64_BYTES",
"ttl_seconds": 86400
}

Before saving, Rankability posts a signed {"type":"verification","challenge":"..."} to your URL. Respond 200 with {"challenge":"<same value>"}. The response is 201 with the subscription id and expires_at.

  • URL: HTTPS on port 443, public address, no credentials, fragment or redirects.
  • Secret: a Standard Webhooks whsec_ key of 24 to 64 bytes. Verify webhook-id, webhook-timestamp and webhook-signature on every delivery.
  • Lifetime: 1 minute to 7 days, default 24 hours. Send the same request again before expires_at to refresh; it keeps the same id.
  • Limit: 100 active subscriptions per credential (409 subscription_limit_reached).
  • Failures: 422 callback_verification_failed with a reason when your endpoint does not answer the challenge.

Each delivery is a signed POST with eventId, name, timestamp and data holding client_id, project_id, record_id, completed_at and the report url. Payloads carry IDs only, never report contents; read the result with the matching GET endpoint. Respond 2xx to acknowledge. Network errors, 408, 429 and 5xx retry with backoff up to six attempts; 410 stops the subscription. A delivery can repeat after a crash, so de-duplicate on eventId. Missed events are not replayed.

GET /events/subscriptions returns your active subscriptions; callback URLs are shown without query strings. DELETE /events/subscriptions/{id} stops one and cancels its queued deliveries. Stopping a subscription another credential owns has no effect.