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

# Using webhooks with the API

> Combine the API and webhooks into one submit, notify, resolve loop.

The API and webhooks are two halves of the same integration. The API is a **pull**
surface — you request state and ask Origami to change it. Webhooks are a **push**
surface — Origami tells you the moment something happens, so you don't have to poll.

| Plane | Direction | Answers |
| - | - | - |
| [v3 API](https://docs.origami.chat/v3/overview.md) | pull (request → response) | "What is the state, and please change it." |
| [Webhooks](https://docs.origami.chat/webhooks/overview.md) | push (event → your endpoint) | "Tell me the moment something happens." |

They are not alternatives. A real integration uses both: the API to submit work and read
results, webhooks to learn when long-running or externally-triggered things happen.

For v3 Jobs, subscribe to `job.*` and skip the poll loop: the webhook tells you
the Job is terminal, then you `GET` it once for the full `result`.

## The submit, notify, resolve loop

The rule of thumb: **the API gives you the id and the final read; the webhook tells you when
to do that read.**

Sequence outreach is the clearest example you can wire up today:

**1. Submit**

Start a sequence — draft one with `POST /api/v2/tables/{tableId}/sequences` or launch it
in the app.

**2. Notify**

`sequence.message.sent` fires when each step is durably sent.
`sequence.reply.received` fires on an inbound reply.

**3. Resolve**

Read the sequence with `GET /api/v2/sequences/{sequenceId}`, then stop or adjust it from
the API or in the app.

For v3 async work (searches, fetches, enrichment, drafts), subscribe to
`job.succeeded` / `job.failed` / `job.cancelled` / `job.needs_input`. The
payload's `job_id` is the same id you poll at
[`GET /api/v3/jobs/{job_id}`](https://docs.origami.chat/v3/reference/jobs-get). Pass `metadata` on
admit so the webhook carries your correlation key.

For `enrich=true` upsert batches, subscribe to `table.run.completed` — the webhook fires when
the parent table run reaches a terminal state (`complete`, `cancelled`, or `failed`). On v3,
the upsert response embeds an `enrichment_job` you can also watch via `job.*`. Missed
delivery on v2? Recover by polling [`GET /api/v2/tables/{tableId}/runs/{runId}`](https://docs.origami.chat/agents/reference/get-table-run)
using the `tableRunId` from the upsert receipt.

## Correlation keys

A webhook payload joins back to API resources through stable ids, so you can round-trip from
a push event to a pull read with no extra mapping.

| Payload field | Read it with |
| - | - |
| `data.job_id` (on `job.*`) | [`GET /api/v3/jobs/{job_id}`](https://docs.origami.chat/v3/reference/jobs-get) |
| `data.metadata` (on `job.*`) | Echo of the object you passed when admitting the Job. |
| `data.campaign_id` (sequencer events) | [`GET /api/v3/send/campaigns/{campaign_id}`](https://docs.origami.chat/v3/reference/send-campaigns-get) |
| `data.sender.id` (sequencer events) | [`GET /api/v3/account/senders/{sender_id}`](https://docs.origami.chat/v3/reference/account-senders-get) |
| `data.run_id` (on `table.run.completed`) | [`GET /api/v2/tables/{tableId}/runs/{runId}`](https://docs.origami.chat/agents/reference/get-table-run) |
| `outreach_target.{table_id, row_id}` | [`GET /api/v3/leads/lists/{list_id}/rows/{row_id}`](https://docs.origami.chat/v3/reference/leads-lists-rows-get) |
| `sequence_id` | v3: the campaign person (`sequence_id`). v2: `GET /api/v2/sequences/{sequenceId}` |

## Auth and security

The two planes use independent credentials. The API authenticates with your `og_live_` API
key. Webhooks authenticate **to your receiver** with an HMAC signature over the delivery body,
which you [verify](https://docs.origami.chat/webhooks/signatures.md) before acting on the payload. Rotating an API key does
not affect webhook signatures, and vice versa.

Webhook payloads expose only user-visible identifiers (email address, LinkedIn handle, display
name) — the same redaction the API serializers apply.


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