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

# Integration webhook events

> Reference for the nine integration webhook events: when each is sent, the fields of its data object, and a synthetic example payload for each one.

Every integration webhook request has the same envelope. The `data` object depends on
the event. Treat payloads as forward-compatible: ignore fields you do not use instead of
rejecting the request. Delivery is at least once and unordered, so
[deduplicate on `id`](https://docs.qwairy.co/developers/integration-webhooks/overview#delivery-guarantees).

## Envelope

| Field | Type | Meaning |
| - | - | - |
| `id` | string | Event identifier, stable across attempts and redeliveries |
| `event` | string | Event type |
| `createdAt` | string | ISO 8601 time of the event |
| `teamId` | string | Team identifier |
| `brandId` | string or null | Workspace identifier, or `null` for team-level events |
| `data` | object | Event-specific fields |

Events contain no prompt or answer text, cited sources, email addresses, person names
or Stripe identifiers.

| Event | Sent when |
| - | - |
| [`run.completed`](#run-completed) | A run finished successfully |
| [`run.failed`](#run-failed) | A run failed |
| [`run.cancelled`](#run-cancelled) | A run was cancelled |
| [`pitch_audit.completed`](#pitch_audit-completed) | A Pitch Audit report is ready |
| [`pitch_audit.failed`](#pitch_audit-failed) | A Pitch Audit failed |
| [`site_audit.completed`](#site_audit-completed) | Every page of a page audit finished |
| [`prompt_suggestions.ready`](#prompt_suggestions-ready) | A prompt suggestion generation finished |
| [`prompt_suggestions.failed`](#prompt_suggestions-failed) | A prompt suggestion generation failed |
| [`webhook.test`](#webhook-test) | You sent a test event |

All timestamps in the examples are synthetic.

## `run.completed`

A run reached a final successful state, whether it was manual or scheduled. `brandId`
is the workspace of the run.

Run events are sent once a run can no longer change. While a run holds a quarantined
answer whose provider payload can still be replayed, for up to 7 days, its event waits.
During that time, [List runs](https://docs.qwairy.co/developers/endpoints/runs/list.md) can already report the
run as final. This applies to `run.failed` and `run.cancelled` too.

| Field | Type | Meaning |
| - | - | - |
| `runId` | string | Run identifier, as in [Get a run](https://docs.qwairy.co/developers/endpoints/runs/get.md) |
| `purpose` | string | `PERIODIC`, `PROMPT_ADDED`, `MANUAL` or `ONBOARDING` |
| `status` | string | `COMPLETED`, `COMPLETED_WITH_WARNINGS` or `NO_WORK` |
| `counts` | object | `requested`, `completed`, `failed`, `skipped` and `cancelled` item counts |
| `creditsDebited` | integer | Credits debited for this processing |
| `createdAt` | string | ISO 8601 creation time of the run |
| `finalizedAt` | string | ISO 8601 time when the run reached its final state |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "run.completed",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": "brand_synthetic_01",
  "data": {
    "runId": "run_synthetic_01",
    "purpose": "MANUAL",
    "status": "COMPLETED_WITH_WARNINGS",
    "counts": { "requested": 40, "completed": 38, "failed": 2, "skipped": 0, "cancelled": 0 },
    "creditsDebited": 76,
    "createdAt": "2026-11-02T09:02:11Z",
    "finalizedAt": "2026-11-02T09:14:07Z"
  }
}
```

## `run.failed`

A run failed, including a planning failure. `brandId` is the workspace of the run.

| Field | Type | Meaning |
| - | - | - |
| `runId` | string | Run identifier, as in [Get a run](https://docs.qwairy.co/developers/endpoints/runs/get.md) |
| `purpose` | string | `PERIODIC`, `PROMPT_ADDED`, `MANUAL` or `ONBOARDING` |
| `status` | string | `FAILED` |
| `counts` | object | `requested`, `completed`, `failed`, `skipped` and `cancelled` item counts |
| `creditsDebited` | integer | Credits debited for this processing |
| `createdAt` | string | ISO 8601 creation time of the run |
| `finalizedAt` | string | ISO 8601 time when the run reached its final state |
| `errorCode` | string | `RUN_PLANNING_FAILED` or `RUN_ALL_ITEMS_FAILED`, without provider output or customer text |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "run.failed",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": "brand_synthetic_01",
  "data": {
    "runId": "run_synthetic_01",
    "purpose": "MANUAL",
    "status": "FAILED",
    "counts": { "requested": 40, "completed": 0, "failed": 0, "skipped": 0, "cancelled": 0 },
    "creditsDebited": 0,
    "createdAt": "2026-11-02T09:02:11Z",
    "finalizedAt": "2026-11-02T09:14:07Z",
    "errorCode": "RUN_PLANNING_FAILED"
  }
}
```

## `run.cancelled`

A run was cancelled. `brandId` is the workspace of the run.

| Field | Type | Meaning |
| - | - | - |
| `runId` | string | Run identifier, as in [Get a run](https://docs.qwairy.co/developers/endpoints/runs/get.md) |
| `purpose` | string | `PERIODIC`, `PROMPT_ADDED`, `MANUAL` or `ONBOARDING` |
| `status` | string | `CANCELLED` |
| `counts` | object | `requested`, `completed`, `failed`, `skipped` and `cancelled` item counts |
| `creditsDebited` | integer | Credits debited for this processing |
| `createdAt` | string | ISO 8601 creation time of the run |
| `finalizedAt` | string | ISO 8601 time when the run reached its final state |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "run.cancelled",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": "brand_synthetic_01",
  "data": {
    "runId": "run_synthetic_01",
    "purpose": "MANUAL",
    "status": "CANCELLED",
    "counts": { "requested": 40, "completed": 12, "failed": 0, "skipped": 0, "cancelled": 28 },
    "creditsDebited": 24,
    "createdAt": "2026-11-02T09:02:11Z",
    "finalizedAt": "2026-11-02T09:14:07Z"
  }
}
```

## `pitch_audit.completed`

A Pitch Audit report is ready. Pitch Audits belong to the team, so `brandId` is `null`.

| Field | Type | Meaning |
| - | - | - |
| `auditId` | string | Pitch Audit identifier, as in [Get Pitch Audit](https://docs.qwairy.co/developers/endpoints/pitch-audits/get.md) |
| `subjects` | integer | Number of audited subjects |
| `creditsDebited` | integer | Credits debited for this processing |
| `completedAt` | string | ISO 8601 completion time |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "pitch_audit.completed",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": null,
  "data": {
    "auditId": "audit_synthetic_01",
    "subjects": 3,
    "creditsDebited": 120,
    "completedAt": "2026-11-02T09:14:07Z"
  }
}
```

## `pitch_audit.failed`

A Pitch Audit failed terminally. `brandId` is `null`.

| Field | Type | Meaning |
| - | - | - |
| `auditId` | string | Pitch Audit identifier |
| `errorCode` | string | `PITCH_AUDIT_FAILED` or `PITCH_AUDIT_PROMPT_PREPARATION_FAILED`, without provider output or customer text |
| `failedAt` | string | ISO 8601 failure time |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "pitch_audit.failed",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": null,
  "data": {
    "auditId": "audit_synthetic_01",
    "errorCode": "PITCH_AUDIT_FAILED",
    "failedAt": "2026-11-02T09:14:07Z"
  }
}
```

## `site_audit.completed`

Every page of a page audit finished. `brandId` is the workspace of the audit.

| Field | Type | Meaning |
| - | - | - |
| `auditId` | string | Audit identifier, the `id` in [Get a page audit](https://docs.qwairy.co/developers/endpoints/site-diagnostics/get-audit.md) |
| `counts` | object | `total`, `succeeded`, `failed` and `skipped` page counts |
| `createdAt` | string | ISO 8601 creation time |
| `completedAt` | string | ISO 8601 time when the audit finished: the last page result, skipped pages included, or the close of queueing, whichever is later. [Get a page audit](https://docs.qwairy.co/developers/endpoints/site-diagnostics/get-audit.md) returns the same value |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "site_audit.completed",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": "brand_synthetic_01",
  "data": {
    "auditId": "site_audit_synthetic_01",
    "counts": { "total": 12, "succeeded": 11, "failed": 1, "skipped": 0 },
    "createdAt": "2026-11-02T09:02:11Z",
    "completedAt": "2026-11-02T09:14:07Z"
  }
}
```

## `prompt_suggestions.ready`

A Prompt Studio generation finished. `brandId` is the workspace of the generation.

`recommendations` is the value that
[Get a suggestion generation](https://docs.qwairy.co/developers/endpoints/prompt-suggestions/get-run.md)
returned for this run when the event was recorded. A later read of the run can
differ, because tracked prompts, competitors and newer generations change it. It
is null when the run stands for no recommendations: a `profile` preparation, a
pool that is no longer the newest usable pool, or a topic that was deleted. Only customer Prompt Studio runs
produce these events, not the public lead-generation tools.

| Field | Type | Meaning |
| - | - | - |
| `runId` | string | Generation identifier, the `id` in [Get a suggestion generation](https://docs.qwairy.co/developers/endpoints/prompt-suggestions/get-run.md) |
| `source` | string | `manual`, `onboarding`, `topic` or `profile` |
| `keywordId` | string or null | Topic of the generation, when there is one |
| `recommendations` | integer or null | Number of recommended suggestions when the event was recorded |
| `completedAt` | string | ISO 8601 completion time |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "prompt_suggestions.ready",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": "brand_synthetic_01",
  "data": {
    "runId": "suggestion_run_synthetic_01",
    "source": "manual",
    "keywordId": null,
    "recommendations": 20,
    "completedAt": "2026-11-02T09:14:07Z"
  }
}
```

## `prompt_suggestions.failed`

A Prompt Studio generation failed. `brandId` is the workspace of the generation.

| Field | Type | Meaning |
| - | - | - |
| `runId` | string | Generation identifier |
| `source` | string | `manual`, `onboarding`, `topic` or `profile` |
| `keywordId` | string or null | Topic of the generation, when there is one |
| `failedAt` | string | ISO 8601 failure time |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "prompt_suggestions.failed",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": "brand_synthetic_01",
  "data": {
    "runId": "suggestion_run_synthetic_01",
    "source": "topic",
    "keywordId": "topic_synthetic_01",
    "failedAt": "2026-11-02T09:14:07Z"
  }
}
```

## `webhook.test`

Sent only by [Send a test event](https://docs.qwairy.co/developers/endpoints/webhooks/test.md), to one endpoint,
even when it is disabled. `brandId` is `null`.

| Field | Type | Meaning |
| - | - | - |
| `message` | string | A fixed test message |

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "webhook.test",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": null,
  "data": {
    "message": "Test event from Qwairy."
  }
}
```


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