---
title: "Completion events"
description: "Signed webhooks when a Tracker scan, Page Audit or Site Audit finishes, shared with the MCP server's events."
canonical_url: "https://developers.rankability.com/guides/events"
section: "Guides"
last_updated: 2026-11-14
---

# Completion events

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

## 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

```http
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.

### 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

`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.
