> ## Documentation Index
> Fetch the complete documentation index at: https://docs.preuve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> One signed POST per finished client report, on the URL your workspace already uses for scanner leads.

A Consultant or Agency workspace can save one webhook URL in
[Dashboard → API](https://preuve.ai/workspace?tab=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

| `X-Preuve-Event` | When |
| - | - |
| `report.completed` | An API-started client report reached `COMPLETED`. Its export is ready. |
| `report.failed` | An API-started client report reached `FAILED`. A deep report's project credit is returned. |
| `report.test` | The dashboard's "Send a report sample" button. Same body as `report.completed`. |
| `lead.completed` | A scanner lead's starter scan finished. |
| `lead.held` | A scanner lead was held because the day's starter scans were used. |
| `lead.test` | The dashboard's "Send a test" button. |

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

| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `User-Agent` | `Preuve-Webhook/1` |
| `X-Preuve-Event` | The event name above |
| `X-Preuve-Delivery` | A UUID per delivery, also `delivery_id` in the body |
| `X-Preuve-Signature` | `sha256=<hex>`, HMAC-SHA256 of the raw body with your secret |

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.

```js theme={null}
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  return (
    expected.length === signatureHeader.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader))
  );
}
```

## Payload: `report.completed`

```json theme={null}
{
  "event": "report.completed",
  "sent_at": "2026-11-09T14:02:11.482Z",
  "delivery_id": "3f1a4c2e-7b8d-4e1f-9a2b-6c5d4e3f2a1b",
  "workspace": { "id": "a1b2c3d4-...", "name": "SEVA Systems", "slug": "seva-systems" },
  "report": {
    "reportId": "9d8c7b6a-...",
    "clientRunId": "portal-2026-11-09-017",
    "status": "COMPLETED",
    "scanType": "deep",
    "title": "Waitlist booking assistant for physiotherapists",
    "reportUrl": "https://preuve.ai/app/agency-report/9d8c7b6a-...",
    "completedAt": "2026-11-09T14:02:09.913Z",
    "export": {
      "json": "https://preuve.ai/api/agent/agency/reports/9d8c7b6a-.../export",
      "markdown": "https://preuve.ai/api/agent/agency/reports/9d8c7b6a-.../export?format=markdown"
    }
  },
  "links": { "dashboard": "https://preuve.ai/workspace" }
}
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.