Completion events
Signed webhooks when a Tracker scan, Page Audit or Site Audit finishes, shared with the MCP server's events.
Completion events
Section titled “Completion 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.
Subscribe
Section titled “Subscribe”POST /events/subscriptionsContent-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. Verifywebhook-id,webhook-timestampandwebhook-signatureon every delivery. - Lifetime: 1 minute to 7 days, default 24 hours. Send the same request again before
expires_atto refresh; it keeps the sameid. - Limit: 100 active subscriptions per credential (
409 subscription_limit_reached). - Failures:
422 callback_verification_failedwith areasonwhen your endpoint does not answer the challenge.
Deliveries
Section titled “Deliveries”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.
List and stop
Section titled “List and stop”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.
