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:
{
"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:
| Header | Value |
|---|---|
Webhook-Id | The delivery ID (whd_…), the same on every retry of the delivery |
Webhook-Timestamp | When this attempt was signed, in Unix seconds |
Webhook-Signature | v1= 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.