# Guide to Origami Webhooks: Features and Best Practices

[Origami](https://origami.chat) is an AI platform for sales prospecting, data enrichment and outbound sequences. Much of its work runs asynchronously: an API Job searching for leads, a table enrichment batch, or a sequence that sends emails and LinkedIn messages over days. Origami's webhooks tell your systems when that work finishes or when a prospect replies, so you don't have to poll.

The sections below walk through Origami's three event families, endpoint setup, signature verification and secret rotation, and the retry rules that decide when Origami drops a delivery or disables your endpoint.

## What are Origami webhooks?

Origami webhooks are signed JSON `POST` requests sent to endpoints you register in **Settings > Developers > Webhooks** or through `POST /api/v3/account/webhooks`. They are in beta, and Origami says event types and payload shapes may still change; orgs with active endpoints get an email before any breaking change. The [overview](https://docs.origami.chat/webhooks/overview) groups the events into API Jobs, tables and the sequencer.

Every delivery is an envelope with four fields: `type`, `id` (equal to the `webhook-id` header), `timestamp` (when the event happened, unchanged on retries) and `data`.

## Origami webhook features

| Feature | Details |
| --- | --- |
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | `webhook-signature` |
| Body | JSON |
| Event routing | Body field `type` |
| Availability | Org admins on paid plans; beta |
| Endpoints | Up to 5 active per organisation |
| Subscriptions | Event types or wildcards (`job.*`, `table.*`, `sequence.*`, `sequence.connection.*`, `*`) |
| Secret | `whsec_` per endpoint, shown once; 24-hour overlap on rotation |
| Timeout | 30 seconds |
| Retries | 10 attempts over about 75 hours, ±15% jitter |
| Auto-disable | On `410 Gone` or about 100 consecutive failures |
| Replay | **Redeliver** in the dashboard, same `webhook-id` |

## Events and payloads

Origami documents 11 event types and doesn't say the list is final; subscribing to `*` includes future types. `webhook.test` is always delivered, whatever you subscribe to.

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `job.succeeded` | A v3 Job finished (searches, fetches, enrichment, campaign drafts, domain purchases, mailbox provisioning, chat messages) | Fetch the result with `GET /api/v3/jobs/{job_id}` |
| `job.failed` | A Job failed; `data.error` has `code` and `message` | Alerting, retries |
| `job.cancelled` | A Job was cancelled; partial work is reported | Cleanup |
| `job.needs_input` | A Job paused for questions (`data.needs_input.questions`) or a human handoff (`data.needs_input.handoff`) | Answer via `POST /api/v3/jobs/{job_id}/input` |
| `table.run.completed` | An `enrich=true` API enrichment batch reached `complete`, `cancelled` or `failed` | Pull enriched rows |
| `sequence.message.sent` | A sequencer email or LinkedIn DM finished sending | Outreach logging |
| `sequence.reply.received` | An inbound email or LinkedIn DM matched an outbound sequence | Notify reps, update the CRM |
| `sequence.connection.requested` | A sequencer LinkedIn invite was sent | Outreach logging |
| `sequence.connection.accepted` | A LinkedIn invite from a sequence was accepted | Follow-up |
| `sequence.comment.posted` | A sequencer LinkedIn comment was published on the prospect's post (likes fire no event) | Outreach logging |
| `webhook.test` | **Test endpoint** in the dashboard, or `POST /api/v3/account/webhooks/{webhook_id}/test` | Connectivity check |

The dashboard's event picker turns on only `sequence.reply.received` and `sequence.connection.accepted` by default.

### Job events

All four `job.*` events share one `data` shape: `job_id`, `operation` (for example `leads.searches.create`), `status`, `sequence`, `target`, `metadata` (the object you passed when you created the Job, echoed back), `credits`, `summary`, `error` and `needs_input`. The summary holds counts and resource IDs, never row-level data, so fetch the Job for the actual results. `sequence` increases with each status change; Origami says to ignore any event whose `sequence` is not greater than the last one you processed for that `job_id`.

### Table events

`table.run.completed` carries `run_id`, `table_id`, `workspace_id`, `organization_id`, `source`, the terminal `status`, `failure_reason`, `created_at`, `completed_at` and `counts` (`complete`, `errored`, `cancelled`). If you miss one after a v3 upsert, call `GET /api/v3/jobs/{job_id}` with the embedded enrichment Job ID. On v2, call `GET /api/v2/tables/{tableId}/runs/{runId}` with the `run_id`.

### Sequencer events

Each sequencer payload includes `campaign_id` (nullable), `sequence_id`, `sender.id` (matching `GET /api/v3/account/senders`) and `outreach_target` (`table_id`, `row_id`, `column_id`, `email`, `linkedin_urn`, `linkedin_slug`).

* `sequence.message.sent`: `message` (`subject`, `body`, `provider_id`, `thread_id`, `rfc_message_id`), `message_id`, `step_index`, `sent_at`.
* `sequence.reply.received`: `reply_message`, `newly_stopped`, and `additional_matched_sequence_ids` when one reply matched several sequences.
* `sequence.connection.requested`: shaped like `message.sent`, with `channel` always `linkedin`; `message.body` is the optional connection note.
* `sequence.connection.accepted`: `original_message_id`, `requested_at`, `connected_at`.
* `sequence.comment.posted`: `comment` (`body`, `comment_id`, `post_url`), `posted_at`.
* `webhook.test`: `triggered_by` (`dashboard` or `api`), `triggered_at`, `message`.

Origami's OpenAPI file defines these envelopes but includes no example bodies, so capture a real delivery before writing fixtures.

## Setting up Origami webhooks

You need an org admin account on a paid plan; the Webhooks section is hidden otherwise. The URL must be public HTTPS. Origami rejects IP literals, non-default ports, credentials in the URL and cloud metadata hostnames.

1. Open **Settings > Developers > Webhooks** and click **New endpoint**.
2. Enter the URL, for example `https://example.com/webhooks/origami`, and an optional description of up to 500 characters.
3. Choose event types from the tree, or tick **Everything**, **Sequencer** or **API Jobs** to subscribe with a wildcard.
4. Copy the `whsec_` secret from the modal and store it as `ORIGAMI_WEBHOOK_SECRET`. It is shown once; afterwards the list only shows the last four characters.
5. Click **Test endpoint** to send a `webhook.test` event.

`POST /api/v3/account/webhooks` does the same from code and also returns the secret only once. To try deliveries on your laptop, use the [Hookdeck CLI](/docs/cli) and register the URL it gives you:

```bash
npx hookdeck-cli listen 3000 origami --path /webhooks/origami

```

**With Hookdeck.** Create an **Origami** source, give its URL to Origami as the endpoint, and paste the full `whsec_` secret into the source. Hookdeck returns `200` to Origami as soon as the request is accepted, well inside the 30-second timeout, and stores requests that fail verification as failures instead of passing them on. Only `POST` requests are accepted.

## Securing Origami webhooks

Origami's [signature page](https://docs.origami.chat/webhooks/signatures) describes the standard scheme: HMAC-SHA256 over `{webhook-id}.{webhook-timestamp}.{raw body}`, keyed with the base64-decoded bytes after `whsec_`, sent as one or more `v1,<base64>` values in `webhook-signature`. During a rotation the header has two values, and either one is enough:

```javascript
const crypto = require('node:crypto');

function decodeBase64(value) {
  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
  const bytes = Buffer.from(value, 'base64');
  return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
    ? bytes : null;
}

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const prefix = headers['webhook-id'] !== undefined ? 'webhook' : 'svix';
  const id = headers[`${prefix}-id`];
  const timestamp = headers[`${prefix}-timestamp`];
  const signature = headers[`${prefix}-signature`];
  if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
      !/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
  const key = decodeBase64(secret.replace(/^whsec_/, ''));
  if (!key) return false;
  const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
  const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    const received = decodeBase64(candidate);
    if (!received) return false;
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

A handler that keeps Job events in order and alerts on replies:

```javascript
const express = require('express');

// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
  try {
    const value = JSON.parse(rawBody.toString('utf8'));
    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
  } catch {
    return null;
  }
}

const app = express();

app.post('/webhooks/origami', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.ORIGAMI_WEBHOOK_SECRET;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  const event = parseJsonObject(req.body);
  if (!event) return res.sendStatus(400); // signed, but not a JSON object
  if (typeof event.type !== 'string' || !event.data || typeof event.data !== 'object') return res.sendStatus(400);
  try {
    if (await store.seen(event.id)) return res.sendStatus(200);

    if (event.type.startsWith('job.')) {
      const last = (await store.lastJobSequence(event.data.job_id)) ?? -1;
      if (event.data.sequence > last) await jobs.apply(event.data);
    } else if (event.type === 'sequence.reply.received') {
      await crm.logReply(event.data.campaign_id, event.data.outreach_target, event.data.reply_message);
    }
    // Return 200 for everything else; other 4xx codes make Origami drop the event.
    await store.markSeen(event.id);
  } catch {
    return res.sendStatus(503); // not processed, so don't acknowledge
  }
  return res.sendStatus(200);
});

```

`store`, `jobs` and `crm` are placeholders for your own code.

Origami asks receivers to reject a `webhook-timestamp` more than five minutes from their clock, and the Standard Webhooks and Svix libraries do this by default. That works for direct delivery because Origami stamps every attempt with a new dispatch time. It doesn't work behind Hookdeck: Hookdeck applies no timestamp tolerance, and when it retries or you replay an event it sends Origami's original headers, so the timestamp may be hours old. Skip the age check in the service behind Hookdeck.

> **Make Origami webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) answers Origami within the 30-second timeout, so a slow deploy never counts towards the 100 failures that disable your endpoint.

## Origami webhook limitations and pain points

### Your status codes can drop or disable deliveries

**The Problem:** Events disappear, or the endpoint stops receiving anything.

**Why It Happens:** Origami retries only `408`, `429`, `5xx` and timeouts. Any other `4xx` and every `3xx` is dropped without retry. A `410 Gone` disables the endpoint, and so do roughly 100 consecutive failures. A redirect after a URL change, or a `404` from a routing mistake, is enough to lose events.

**Workarounds:**

* Return `200` for events you don't handle, and `5xx` only when you want a retry.
* Watch for the endpoint being disabled and re-enable it from the dashboard after a fix.

**How Hookdeck Can Help:** Hookdeck always answers `200`, so Origami never drops or disables the endpoint because of your service. Failures between Hookdeck and your service raise [issues](/docs/issues) and are retried there.

### Origami's suggested dedupe window is too short

**The Problem:** A retry arrives hours later and is processed twice.

**Why It Happens:** Origami's retry page suggests keeping seen IDs for five minutes, but its retry schedule runs for about 75 hours. A retry after 5 minutes, 30 minutes or 24 hours slips past a five-minute cache.

**Workarounds:**

* Keep processed `webhook-id` values for at least as long as the retry schedule, about 75 hours, or permanently in a database table.

**How Hookdeck Can Help:** [Deduplication](/docs/deduplication) on the `webhook-id` header filters repeats before they reach your code.

### The secret is shown once

**The Problem:** The secret is lost after the creation modal closes.

**Why It Happens:** Origami reveals it once in the dashboard or API response, then shows only the last four characters. Its docs print only the placeholder `whsec_XXXXXXXX`.

**Workarounds:**

* Copy it straight into your secret manager. If it's lost, use **Rotate secret**; the old one stays valid for 24 hours while you switch.

**How Hookdeck Can Help:** Keeping the secret on the Hookdeck source means you update it in one place on rotation.

### Beta payloads and no examples

**The Problem:** Fields change, or your parser fails on a body you've never seen.

**Why It Happens:** Webhooks are in beta, and the OpenAPI file has schemas but no example bodies. The curl sample on the signatures page even uses `sequence.email.sent`, which isn't a listed type.

**Workarounds:**

* Parse defensively, ignore unknown fields and types, and capture real deliveries from **Test endpoint** and a test sequence.

**How Hookdeck Can Help:** Every request is stored, so you can inspect real bodies and [replay](/docs/retries) them against an updated handler.

### Five endpoints per organisation

**The Problem:** Separate endpoints for staging, production and each consuming service run out quickly.

**Why It Happens:** Origami caps an organisation at five active endpoints.

**Workarounds:**

* Use one endpoint per environment and fan out internally by `type`.

**How Hookdeck Can Help:** One Origami source can feed several [connections](/docs/connections), each with its own [filter](/docs/filters) on `type`.

## Best practices

### Fetch results rather than trusting summaries

`job.succeeded` carries counts and IDs only. Call `GET /api/v3/jobs/{job_id}` for the rows, and use the echoed `metadata` to find the request that started the Job.

### Order Job events by `sequence`

Store the highest `data.sequence` per `job_id` and ignore anything lower or equal, as Origami recommends.

### Use the right timestamp

The envelope's `timestamp` is when the action happened. The `webhook-timestamp` header is only the dispatch time. Record the former in your CRM. Our [guide to webhook idempotency](/webhooks/guides/implement-webhook-idempotency) explains how to keep the processed-ID record and your writes consistent.

### Exempt the route from CSRF and body parsing

Frameworks with CSRF protection must skip this route, and the signature needs the unparsed body: `express.raw()` in Express or `await request.text()` in a Next.js route handler.

## Conclusion

Origami's webhooks report the result of long-running Jobs, enrichment batches and outbound sequences, with Standard Webhooks signatures and a generous 75-hour retry schedule. The traps are in the details: status codes that silently drop events, a dedupe window much shorter than the retries, a secret shown once, and beta payloads with no examples.

[Hookdeck Event Gateway](https://hookdeck.com) keeps your endpoint enabled, deduplicates retries and stores every payload for inspection. [Sign up for free](https://dashboard.hookdeck.com/signup) and send Origami's test event to a Hookdeck source.