# Origami Webhooks

[Origami](https://origami.chat) POSTs a signed JSON envelope to your endpoint when a v3 Job
changes status, a table enrichment run finishes, or the sequencer sends a message, gets a reply,
or makes LinkedIn connections and comments. Webhooks are in **beta**, so event types and payload
shapes may still change. Deliveries use Standard Webhooks
signing with three headers: `webhook-id`, `webhook-timestamp` and `webhook-signature`. The body is
`{ type, id, timestamp, data }`: `type` is the event name, `id` equals the `webhook-id` header,
`timestamp` is the event time, and `data` holds the event.

## When to Use This Skill

* How do I receive Origami webhooks?
* How do I verify Origami webhook signatures (`webhook-signature`)?
* How do I handle `job.succeeded`, `table.run.completed` or `sequence.reply.received` events?
* How do I route a sequencer event back to its campaign (`campaign_id`, `sender.id`)?
* Why is my Origami webhook signature verification failing, or rejecting Hookdeck retries?

## Verification (core)

Signed content is `{webhook-id}.{webhook-timestamp}.{raw body}`. Origami signs it with
HMAC-SHA256 using the base64-decoded secret (the part after `whsec_`), base64-encodes the result,
and sends one or more space-separated `v1,<signature>` entries (two during a secret rotation).
Use the `standardwebhooks` library, which compares in constant time. Read the `webhook-*` headers,
and when `webhook-id` is absent fall back to the `svix-*` headers (`svix-id`, `svix-timestamp`,
`svix-signature`), then hand the library the values under the `webhook-*` names.

```javascript
import { Webhook } from 'standardwebhooks';

const prefix = req.headers['webhook-id'] ? 'webhook' : 'svix';
const id = req.headers[`${prefix}-id`];
const timestamp = req.headers[`${prefix}-timestamp`];
const signature = req.headers[`${prefix}-signature`];
// rawBody: the raw Buffer/string, never re-serialized JSON
new Webhook(process.env.ORIGAMI_WEBHOOK_SECRET).verify(rawBody, {
  'webhook-id': id, 'webhook-timestamp': timestamp, 'webhook-signature': signature,
}); // throws on a bad signature or a timestamp outside the window
const event = JSON.parse(rawBody.toString('utf8')); // parse only after verify passes

```

```python
from standardwebhooks import Webhook, WebhookVerificationError

wh = Webhook(os.environ["ORIGAMI_WEBHOOK_SECRET"])  # "whsec_..."
wh.verify(raw_body, {"webhook-id": id, "webhook-timestamp": ts, "webhook-signature": sig})

```

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/origami-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/origami-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/origami-webhooks/examples/fastapi/).

Each endpoint has its own `whsec_...` signing secret, shown once when you create it in
**Settings → Developers → Webhooks** (or returned by `POST /api/v3/account/webhooks`). Keep the
full value in `ORIGAMI_WEBHOOK_SECRET`. Origami's docs print only a placeholder
(`whsec_XXXXXXXX`), so check the real value against what the dashboard shows. Handlers fail
closed: with the variable unset they return 500 instead of accepting anything. A missing header
or bad signature gets 400.

With Express, read the body with `express.raw({ type: '*/*' })` so any content type reaches the
verifier as the exact bytes Origami signed, and parse JSON only after the check.

### Hookdeck retries and replays hit the 5-minute window

The `standardwebhooks` library always enforces a fixed 5-minute timestamp window, and it can't
be configured. Hookdeck retries and replays resend the **original** `webhook-timestamp`, so the
library rejects any retry or replay that happens more than 5 minutes after the original
delivery. If you verify behind Hookdeck (or replay old events), use the manual verifier in
[references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/origami-webhooks/references/verification.md), where the window can be dropped or
widened. Deduplicate on `webhook-id` instead of relying on the timestamp.

## Common Event Types

11 events are documented (the list may not be exhaustive). The name is `type` in the JSON body.
The examples handle all of these:

| Event | Triggered When |
| --- | --- |
| `job.succeeded` | A v3 Job finished successfully (`data.summary` has counts and resource ids) |
| `job.failed` | A Job failed (`data.error` has `code` and `message`) |
| `job.cancelled` | A Job was cancelled (partial work is reported) |
| `job.needs_input` | A Job paused for questions or a human handoff (`data.needs_input`) |
| `table.run.completed` | An enrichment batch reached `complete`, `cancelled` or `failed` |
| `sequence.message.sent` | A sequencer email or LinkedIn DM finished sending |
| `sequence.reply.received` | An inbound email or LinkedIn DM matched an outbound sequence |
| `sequence.connection.requested` | A sequencer LinkedIn invite was sent |
| `sequence.connection.accepted` | A LinkedIn invite from a sequence was accepted |
| `sequence.comment.posted` | A sequencer LinkedIn comment was published |
| `webhook.test` | You clicked **Test endpoint** (always delivered) |

See [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/origami-webhooks/references/overview.md) for payload shapes and the retry schedule.

## Environment Variables

```bash
# Signing secret of the webhook endpoint (starts with whsec_)
ORIGAMI_WEBHOOK_SECRET=whsec_xxxxx

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 origami --path /webhooks/origami

```

Register the tunnel URL as an endpoint in **Settings → Developers → Webhooks**, then click
**Test endpoint** to send a `webhook.test` event.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/origami-webhooks/references/overview.md) - Origami webhook concepts, envelope, events, retries
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/origami-webhooks/references/setup.md) - Create an endpoint, copy the secret, rotate it
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/origami-webhooks/references/verification.md) - Standard Webhooks verification, header fallback, manual verifier, timestamp window