Gareth Wilson Gareth Wilson

Guide to Origami Webhooks: Features and Best Practices

Published


Origami 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 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

FeatureDetails
SignatureStandard Webhooks HMAC-SHA256
Signature headerwebhook-signature
BodyJSON
Event routingBody field type
AvailabilityOrg admins on paid plans; beta
EndpointsUp to 5 active per organisation
SubscriptionsEvent types or wildcards (job.*, table.*, sequence.*, sequence.connection.*, *)
Secretwhsec_ per endpoint, shown once; 24-hour overlap on rotation
Timeout30 seconds
Retries10 attempts over about 75 hours, ±15% jitter
Auto-disableOn 410 Gone or about 100 consecutive failures
ReplayRedeliver 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.

EventTriggered WhenCommon Use Cases
job.succeededA 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.failedA Job failed; data.error has code and messageAlerting, retries
job.cancelledA Job was cancelled; partial work is reportedCleanup
job.needs_inputA 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.completedAn enrich=true API enrichment batch reached complete, cancelled or failedPull enriched rows
sequence.message.sentA sequencer email or LinkedIn DM finished sendingOutreach logging
sequence.reply.receivedAn inbound email or LinkedIn DM matched an outbound sequenceNotify reps, update the CRM
sequence.connection.requestedA sequencer LinkedIn invite was sentOutreach logging
sequence.connection.acceptedA LinkedIn invite from a sequence was acceptedFollow-up
sequence.comment.postedA sequencer LinkedIn comment was published on the prospect's post (likes fire no event)Outreach logging
webhook.testTest endpoint in the dashboard, or POST /api/v3/account/webhooks/{webhook_id}/testConnectivity 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 and register the URL it gives you:

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 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:

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:

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 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 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 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 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, each with its own filter 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 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 keeps your endpoint enabled, deduplicates retries and stores every payload for inspection. Sign up for free and send Origami's test event to a Hookdeck source.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.