Skip to content
Hayonix

Concepts

Webhooks and signatures

Receive a signed HTTP callback when a serverless job finishes, verify its signature, and handle retries and duplicates.

Completion webhooks

A serverless endpoint can call your URL when each of its jobs finishes. Set webhook_url on the endpoint for every job, or on a single job when you submit it (null turns it off for that job). The delivery is a POST with a JSON body:

JSON
{
  "id": "whd_…",
  "object": "event",
  "type": "serverless.job.finished",
  "created_at": "2026-01-01T00:00:00.000Z",
  "data": { "object": "serverless_job", "id": "sjb_…", "state": "succeeded", "output": { … } }
}

data is the job as GET /v1/serverless/jobs/{job_id} returns it.

Verify the signature

Each delivery is signed with the endpoint's webhook secret (whs_…), returned once when the endpoint is created and again when you rotate it (POST /v1/serverless/endpoints/{endpoint_id}/rotate-webhook-secret). Three headers come with it:

HeaderValue
Webhook-IdThe delivery ID (whd_…), the same on every retry of the delivery
Webhook-TimestampWhen this attempt was signed, in Unix seconds
Webhook-Signaturev1= and the hex HMAC-SHA256 of <timestamp>.<body> with the secret

To verify: compute the HMAC over the timestamp, a dot and the raw request body (before any JSON parsing), compare it with the header in constant time, and reject a timestamp more than five minutes from your clock, so a captured delivery cannot be replayed later.

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

/** True when `body` (the raw request body, unparsed) was signed with `secret` recently. */
export function verifyWebhook(
  secret: string,
  headers: { 'webhook-signature': string; 'webhook-timestamp': string },
  body: string,
  toleranceSeconds = 300,
): boolean {
  const timestamp = Number(headers['webhook-timestamp']);
  if (!Number.isInteger(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false; // replayed
  const expected = `v1=${createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex')}`;
  const given = headers['webhook-signature'].trim();
  return (
    expected.length === given.length && timingSafeEqual(Buffer.from(expected), Buffer.from(given))
  );
}

Retries and duplicates

Answer with any 2xx status within 10 seconds to acknowledge a delivery. Any other answer, a timeout or a network error is retried with exponential backoff, up to 8 attempts, after which the delivery is marked failed. GET /v1/serverless/endpoints/{endpoint_id}/webhook-deliveries shows every delivery and its attempts.

A delivery can arrive more than once (your answer may be lost on the way back), so deduplicate on Webhook-Id. Acknowledge quickly and do slow work afterwards.

Destinations must be public: URLs that resolve to private, loopback or link-local addresses are refused.

When you rotate the secret, the old one stops signing at once: deploy the new secret to your receiver before or right after you rotate.