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

> Receive signed JSON events when a run, audit or prompt generation finishes, with retries, a 30-day delivery log and redelivery, managed through the REST API.

Integration webhooks tell your systems that processing has finished, so you do not
have to poll. Qwairy sends a signed JSON `POST` request to your HTTPS endpoint when
a run, a Pitch Audit, a page audit or a prompt suggestion generation reaches a final
state. You manage endpoints with the [REST API](https://docs.qwairy.co/developers/endpoints/webhooks/list.md).

> [!NOTE]
>
> Integration webhooks are separate from the [outbound webhooks](https://docs.qwairy.co/developers/webhooks.md)
> of white-label teams, which replace the weekly-report and export-ready emails. They
> use different endpoints, events, payloads and settings, and they are not connected
> to alerts. Configuring one never changes the other.

## Availability

Integration webhooks are available on **Business**, **Agency Business** and
**Enterprise** plans. Creating, changing, rotating and deleting an endpoint are API
commands, so they also need an API token with write access enabled. An Owner or a
Manager enables it for each token in **Team Management > REST API**. See
[Writing data](https://docs.qwairy.co/developers/writing-data.md).

## Set up an endpoint

**1. Create the endpoint**

Call [Create a webhook endpoint](https://docs.qwairy.co/developers/endpoints/webhooks/create.md) with your
public HTTPS URL and the [events](https://docs.qwairy.co/developers/integration-webhooks/events.md) you want.
Limit it to some workspaces with `brandIds`, or leave it empty to receive every
workspace of the team.

**2. Store the signing secret**

The secret is in the response and cannot be read again. Keep it in a secret manager.

**3. Verify signatures**

Check every request as described in [Verify signatures](https://docs.qwairy.co/developers/integration-webhooks/verify-signatures.md),
and reject unsigned or mis-signed calls. Every key of the team that can read its webhooks,
read-only keys included, receives the full endpoint URL. A token embedded in the URL is
therefore not a secret from those keys.

**4. Send a test event**

Call [Send a test event](https://docs.qwairy.co/developers/endpoints/webhooks/test.md), then read the result in
[List deliveries](https://docs.qwairy.co/developers/endpoints/webhooks/deliveries.md).

A team can have at most **10 endpoints**.

An endpoint receives only events that occur after it was created. Missed event
creation is retried every ten minutes within the 30-day journal window; recovery
does not subscribe a new endpoint to earlier events. The `brandIds` filter applies
only to workspace events. Subscribed team-level Pitch Audit events are delivered
regardless of that filter.

## What Qwairy sends

Every request is a `POST` with a JSON body. The [envelope](https://docs.qwairy.co/developers/integration-webhooks/events.md#envelope)
is the same for every event, and `data` depends on the event.

| Header | Value |
| - | - |
| `X-Qwairy-Event` | Event type, the same as `event` in the body |
| `X-Qwairy-Timestamp` | Unix time in seconds when this attempt was signed |
| `X-Qwairy-Delivery` | Delivery identifier, stable across the attempts of one delivery |
| `X-Qwairy-Signature` | `sha256=` followed by the hexadecimal HMAC-SHA256 of the request |

Events carry identifiers, statuses, counts and timestamps. They never contain prompt
or answer text, cited sources, email addresses, person names or Stripe identifiers.
Read the details you need from the REST API with the identifiers in the event.

## Delivery guarantees

* Delivery is **at least once**. The same event can reach you more than once.
* Order is **not guaranteed**. A later event can arrive before an earlier one.
* Deduplicate on the event `id`. It is the same across attempts and redeliveries.
* Answer with any `2xx` status within **10 seconds**. Any other outcome is a failure.
* Redirects are **not followed**. Register the final URL.
* Respond quickly, then process the event asynchronously.

## Retries and automatic disabling

If an attempt fails, Qwairy retries up to eight attempts in total, at these offsets from the
start of the delivery cycle:

| Attempt | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
| - | - | - | - | - | - | - | - | - |
| Offset | 0 | 1 min | 5 min | 30 min | 2 h | 6 h | 12 h | 24 h |

For a recovered event, the cycle starts when its delivery is queued, not at the
original event time. A manual redelivery starts a new cycle with the same event ID.
A delivery that fell behind this schedule, for example while deliveries were paused or
the endpoint was disabled, keeps at least the gap between two consecutive attempts after
its last attempt, so its remaining attempts do not all run within minutes.

Failures disable an endpoint only at a failed attempt: an attempt that fails when the
current failure streak started at least **72 hours** earlier, with no successful
delivery since. Time alone never disables an endpoint. An endpoint that receives no
attempt, for example while deliveries are paused or while no event is due, stays
enabled until its next failed attempt. An endpoint disabled this way has the
`disabledReason` `FAILING`.

The team's Owners receive an operational email in the minutes after the endpoint is
disabled; this is not an Alert. An email that cannot be sent is retried until 7 days
after the endpoint was disabled, then abandoned. Fix your receiver, then enable the
endpoint again with [Update a webhook endpoint](https://docs.qwairy.co/developers/endpoints/webhooks/update.md).
Re-enabling clears the failure state and starts a new episode: a new streak of
72 hours of failures can disable the endpoint again, and the Owners are emailed again.

## Delivery log and redelivery

Qwairy keeps the delivery log for **30 days**. Read it with
[List deliveries](https://docs.qwairy.co/developers/endpoints/webhooks/deliveries.md). To recover a missed event,
[redeliver](https://docs.qwairy.co/developers/endpoints/webhooks/redeliver.md) a succeeded, exhausted or cancelled
delivery from the last 30 days. The redelivered event keeps its original `id`.
Retention starts when the delivery is created, including for a recovered event.
An accepted redelivery cycle is retained for 30 days from its start; an older
source event never shortens that cycle's retries.

Pausing an endpoint preserves pending deliveries but stops new event enrollment.
A test event can still be sent. Deleting an endpoint cancels queued deliveries;
an HTTP request already in flight can still arrive. If a workspace changes team,
its existing delivery history remains with the original team, but pending
workspace events are cancelled when their ownership is checked for delivery.

## Manage endpoints

| Task | Reference |
| - | - |
| List endpoints | [List webhook endpoints](https://docs.qwairy.co/developers/endpoints/webhooks/list.md) |
| Create an endpoint | [Create a webhook endpoint](https://docs.qwairy.co/developers/endpoints/webhooks/create.md) |
| Read an endpoint | [Get a webhook endpoint](https://docs.qwairy.co/developers/endpoints/webhooks/get.md) |
| Change or pause an endpoint | [Update a webhook endpoint](https://docs.qwairy.co/developers/endpoints/webhooks/update.md) |
| Delete an endpoint | [Delete a webhook endpoint](https://docs.qwairy.co/developers/endpoints/webhooks/delete.md) |
| Change the secret | [Rotate the signing secret](https://docs.qwairy.co/developers/endpoints/webhooks/rotate-secret.md) |
| Check your receiver | [Send a test event](https://docs.qwairy.co/developers/endpoints/webhooks/test.md) |
| Inspect attempts | [List deliveries](https://docs.qwairy.co/developers/endpoints/webhooks/deliveries.md) |
| Replay an event | [Redeliver an event](https://docs.qwairy.co/developers/endpoints/webhooks/redeliver.md) |


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