HTTP Contract

A serverless endpoint is two HTTPS routes that Hatchet calls: a healthcheck and a trigger. @hatchet-dev/serverless implements both for Cloudflare Workers, Vercel and Node servers. This page describes the contract itself, so you can serve an endpoint from another language or platform, or know what the package does on your behalf.

An endpoint that implements only what's on this page serves tasks that are functions of their input: Hatchet delivers each one as a signed POST and reads the response as the task's output. Durable tasks, and tasks that wait for child runs or read streams while they run, are invoked over a websocket with a frame protocol that the TypeScript package implements. An endpoint without it reports durable: { "supported": false } and lists no tasks, and Hatchet delivers every task as a POST.

Routes

You choose both URLs when you register the endpoint. Both must be https at a public address on port 443; Hatchet doesn't follow redirects.

Verifying requests

Every request carries three headers:

Verify before doing any work, in this order:

1. Compute the HMAC-SHA256 of the raw body (the bytes as received, before any JSON parsing) with the signing secret, and compare it with the header in constant time. Reject with 401 on a mismatch.
2. Check timestampUnixSeconds in the body against your clock. Reject a value more than 5 minutes away in either direction, so a captured request can't be replayed later.
3. If you know your endpoint's id, compare it with endpointId in the body. Reject with 403 on a mismatch, so a request signed for another endpoint that shares the secret can't be presented to this one.

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

function verify(rawBody: string, signature: string, secret: string): boolean {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  return (
    expected.length === signature.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
  );
}

Within the 5 minute window a delivery may be repeated, for example after a timeout. Key side effects on endpointId, taskRunExternalId and retryCount together, so a repeated delivery of the same attempt is idempotent.

Healthcheck

Hatchet sends:

{ "endpointId": "0f7a…", "timestampUnixSeconds": 1761235200 }

The endpoint answers 200 with the workflows it serves. The definitions use the same format a worker registers with, so every engine-side option (retries, timeouts, rate limits, concurrency, triggers, DAG parents, conditions) is available:

{
  "workflows": [
    {
      "name": "echo",
      "tasks": [{ "readableId": "echo", "action": "echo:echo", "retries": 3 }]
    },
    {
      "name": "pipeline",
      "tasks": [
        { "readableId": "fetch", "action": "pipeline:fetch" },
        {
          "readableId": "summarize",
          "action": "pipeline:summarize",
          "parents": ["fetch"]
        }
      ]
    }
  ],
  "durable": { "supported": false },
  "runtime": { "name": "python", "sdkVersion": "1.0.0" }
}

Hatchet registers the workflows whenever their definitions change and ignores unknown fields. By default one healthcheck may declare at most 200 workflows and 500 actions, and must answer within 10 seconds. Two endpoints of one tenant may declare the same workflow; both then serve it, like two workers.

Trigger

Hatchet sends the task in an envelope:

{
  "endpointId": "0f7a…",
  "timestampUnixSeconds": 1761235200,
  "version": 1,
  "action": {
    "tenantId": "…",
    "workflowRunId": "…",
    "taskRunExternalId": "…",
    "actionId": "echo:echo",
    "actionType": "START_STEP_RUN",
    "actionPayload": "{\"input\":{\"message\":\"hello\"},\"parents\":{},\"triggered_by\":\"manual\"}",
    "taskName": "echo",
    "retryCount": 0,
    "jobId": "…",
    "jobName": "echo",
    "jobRunId": "…",
    "taskId": "…"
  }
}

action.actionId names the task to run. action.actionPayload is a JSON string whose input is the task's input and whose parents holds the outputs of the task's DAG parents by task name. retryCount is 0 on the first attempt.

The response is read as the task's result:

On any non-2xx response, a body of the form { "error": "…", "retry": false } overrides both: error becomes the task's error message and retry decides whether it's retried. Use it to fail a task permanently from a 500, or to ask for a retry from a 4xx.

A response body over 4 MiB fails the task without a retry. Cancelling a run closes the connection; if your platform exposes the request's abort signal, stop the work when it fires.

Node servers

For a Node process you run yourself, a container or a custom server, @hatchet-dev/serverless/node implements the full contract, including the websocket:

import { createServer } from "@hatchet-dev/serverless/node";
import { workflows } from "./tasks";

createServer({ workflows }).listen(3000); // POST /hatchet/healthcheck, /hatchet/trigger and the upgrade

nodeHandler({ workflows }) is the same endpoint as an http request listener for a server you already have, usable as Express middleware. The websocket needs the ws package; without it the server reports that it doesn't serve durable tasks, and Hatchet delivers every non-durable task as a POST, where a wait for a child run or a stream read fails. The server reads HATCHET_SIGNING_SECRET, HATCHET_CLIENT_TOKEN and the optional HATCHET_ENDPOINT_ID from the environment and takes the same options as the Vercel adapter.