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