Receive run webhooks

Add an HTTPS webhook URL to a routine and Work on Repeat posts a signed event every time a run finishes. Two events exist: run.succeeded and run.failed.

The signing secret is returned once, in the response that created or updated the routine, and only its encrypted form is stored. If you lose it, set the webhook URL again to rotate the secret.

The delivery contract

Every attempt carries four headers:

X-Work-On-Repeat-Event         run.succeeded | run.failed
X-Work-On-Repeat-Request-Id    stable across retries — use it to deduplicate
X-Work-On-Repeat-Timestamp     unix seconds
X-Work-On-Repeat-Signature     v1=<hex hmac-sha256>

The signature is computed over `${timestamp}.${rawBody}` using the routine's signing secret. Verify it against the exact bytes received, before parsing — re-serialising the JSON changes the digest.

See Webhook reference for the full payload schema.

Write the receiver

import { createHmac, timingSafeEqual } from "node:crypto";

const REPLAY_WINDOW_SECONDS = 5 * 60;

export function verify(
  secret: string,
  timestamp: string,
  rawBody: string,
  signature: string,
  now = new Date(),
) {
  const sent = Number(timestamp);
  if (!Number.isInteger(sent)) return false;

  // Reject stale timestamps before spending time on the digest.
  const current = Math.floor(now.getTime() / 1_000);
  if (Math.abs(current - sent) > REPLAY_WINDOW_SECONDS) return false;

  const digest = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`, "utf8")
    .digest("hex");
  const expected = Buffer.from(`v1=${digest}`);
  const received = Buffer.from(signature);

  return (
    expected.byteLength === received.byteLength &&
    timingSafeEqual(expected, received)
  );
}

Testing locally

Point the routine's webhook URL at a tunnel to your machine and run the routine manually. The run detail shows each webhook delivery with its attempt count and response code, so you can confirm the receiver's behaviour without guessing.

Related