Skip to main content
A Consultant or Agency workspace can save one webhook URL in Dashboard → API. Every new scanner lead is posted there, and so is every client report started through POST /api/agent/agency/analyses once it reaches a terminal status. One URL, one signing secret, one event header: a portal that polls GET /api/agent/agency/reports/{id} can stop polling. Reports started from the dashboard itself are not posted. They are the consultant’s own clicks, and a channel wired for the portal’s runs should not hear about them. The list route still returns them.

Events

Each (report, event) pair is sent once. A retried run on our side never produces a second report.completed for the same report. Delivery is one attempt with a 5 second timeout and no retry, so a receiver that was down keeps polling for that one report. Answer with any 2xx; redirects are not followed.

Headers

A hooks.slack.com URL gets { "text": "..." } instead, with no signature: one readable line per event.

Verifying the signature

The secret is shown once, when the URL is saved. Compute the HMAC over the raw request bytes, before any JSON parsing, and compare in constant time.

Payload: report.completed

Both events cover deep reports and Starter Scans started through the API (scanType says which). Reports started from the dashboard or the scanner never send them. report carries the same field names as the poll response, plus the clientRunId you sent at the start, the report’s title and the two export URLs. The body never carries the idea text or the report content: fetch export.json or export.markdown with a key holding agency:read, exactly as you would after a poll. On report.failed, status is FAILED, completedAt and export are null.

Testing a receiver

Save the URL, then use the two buttons under it: “Send a test” posts a lead.test, “Send a report sample” posts a report.test with the shape above and a random reportId. Both are signed with your secret, so a receiver that verifies the sample verifies the real thing. The sample’s export URLs answer 404 REPORT_NOT_FOUND: do not fetch them, check the event name first.