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

# Webhooks overview

> Get a signed HTTPS POST when a day's tracking for a brand is scored.

Webhooks tell your systems when something happens in Quotable, so you don't have to poll the API. Quotable sends a signed JSON `POST` to an HTTPS URL you control, retries it if your server doesn't answer, and logs every attempt.

## Events

| Event | Sent when |
| - | - |
| `tracking.run.finalized` | A day's tracking for a brand was scored. |

Each endpoint subscribes to the events and brands you choose. See [Events](https://docs.usequotable.com/webhooks/events.md) for every payload.

## What a delivery looks like

```http theme={"system"}
POST /hooks/quotable HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: Quotable-Webhooks/1
X-Quotable-Event-Id: 5d1e7a3c-2b4f-4c6e-8a0d-9f1b3c5e7a20
X-Quotable-Event-Type: tracking.run.finalized
X-Quotable-Delivery-Id: e2a4c6e8-0b1d-4f3a-9c5e-7b9d1f3a5c71
X-Quotable-Timestamp: 1790848845
X-Quotable-Signature: v1=6b3f0e4c2a9d8e7f1c5b4a3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f

{
  "id": "5d1e7a3c-2b4f-4c6e-8a0d-9f1b3c5e7a20",
  "type": "tracking.run.finalized",
  "schema_version": 1,
  "occurred_at": "2026-10-01T10:00:45.112Z",
  "org_id": "8f3c2a1e-5b7d-4e9a-9c1f-2d6b8a4e7f10",
  "project_id": "c4a1e8f2-7d3b-4c6a-9e5f-1b2d3c4e5f60",
  "resource": {
    "type": "project",
    "id": "c4a1e8f2-7d3b-4c6a-9e5f-1b2d3c4e5f60",
    "href": "https://app.usequotable.com/api/v1/projects/c4a1e8f2-7d3b-4c6a-9e5f-1b2d3c4e5f60"
  },
  "data": {
    "run_date": "2026-10-01",
    "score": 43.8,
    "mention_rate": 0.6111111111111112,
    "answers_scored": 36
  }
}
```

### The envelope

Every event has the same outer shape. Only `data` differs by event type.

| Field | Type | Meaning |
| - | - | - |
| `id` | UUID | The event id. The same across every retry and every endpoint. Use it to deduplicate. |
| `type` | string | The event type, for example `tracking.run.finalized`. See [Events](https://docs.usequotable.com/webhooks/events.md). |
| `schema_version` | integer | The payload version. `1` for every event today. |
| `occurred_at` | ISO 8601 | When the event happened, in UTC. |
| `org_id` | UUID | Your workspace id, the same as `organization_id` from `GET /me`. |
| `project_id` | UUID | The brand the event is about. |
| `resource` | object | What to fetch for the full record: `type`, `id`, and `href`, an API URL or `null` when the API has no endpoint for that resource. |
| `data` | object | The event-specific fields. |

Payloads are deliberately small: ids, outcomes and a link. Fetch the full record from the [API](https://docs.usequotable.com/api-reference/introduction.md) with your own key when you need it. Deliveries never carry prompts, answer text or credentials.

### Headers

| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `User-Agent` | `Quotable-Webhooks/1` |
| `X-Quotable-Event-Id` | The event id, same as `id` in the body. |
| `X-Quotable-Event-Type` | The event type, same as `type` in the body. |
| `X-Quotable-Delivery-Id` | The id of this event's delivery to this endpoint. It stays the same across retries and manual redeliveries, and it's what the delivery log shows. |
| `X-Quotable-Timestamp` | Unix time in seconds when this attempt was signed. |
| `X-Quotable-Signature` | `v1=<hex>`, or two comma-separated values during a secret rotation. See [Verify signatures](https://docs.usequotable.com/webhooks/verify-signatures.md). |

## How your endpoint should respond

**1. Verify the signature**

Check `X-Quotable-Signature` against the raw body before you trust anything in it. Reject deliveries whose timestamp is more than 5 minutes from your clock.

**2. Deduplicate on the event id**

Deliveries are at-least-once. Store each `id` you've processed and skip repeats.

**3. Answer 2xx within 10 seconds**

Any `2xx` status counts as delivered. Do slow work after you respond, for example on a queue.

Anything else counts as a failed attempt and is retried: a `3xx` (redirects are never followed), `4xx` or `5xx` status, a timeout after 10 seconds, or a connection error. See [Delivery and retries](https://docs.usequotable.com/webhooks/delivery-and-retries.md).

## Requirements

* The URL must use `https://` and be reachable from the public internet. Private and internal addresses are refused.
* The URL can't contain a username or password. Authenticate deliveries with the signature instead.
* A workspace can have up to **10 endpoints**.
* Only the workspace owner and integration admins can add or change endpoints. Every member can see them and their delivery logs.

## Next steps

> [card] [Events](https://docs.usequotable.com/webhooks/events.md)
>
> Every event type with its full payload.

> [card] [Verify signatures](https://docs.usequotable.com/webhooks/verify-signatures.md)
>
> Copy-paste verification for Node.js and Python.

> [card] [Manage endpoints](https://docs.usequotable.com/webhooks/manage-endpoints.md)
>
> Add, pause, rotate and redeliver from Settings.

> [card] [Slack alerts recipe](https://docs.usequotable.com/guides/slack-alerts-from-webhooks.md)
>
> Post daily visibility scores to a Slack channel.


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