Let GetRatchet call your HTTPS endpoint with signed jobs.
HTTP workers
An HTTP worker is an HTTPS endpoint you own — a Vercel route, an AWS Lambda function URL, any server — that GetRatchet calls with each matching durable job. GetRatchet never runs your code: it sends a signed request, waits for the response and records the result with the same leases, retries, circuits and dependencies as a polling worker. HTTP workers are included in the Pro plan.
Register an endpoint
In the console, open Workers → HTTP workers, or use an administrator key:
curl -X POST https://getratchet.app/api/v1/http-workers \
-H "Authorization: Bearer $GETRATCHET_ADMIN_KEY" -H 'Content-Type: application/json' \
-d '{ "name": "vercel", "url": "https://example.com/api/getratchet",
"handlers": [{ "name": "send_email", "version": "1" }], "concurrency": 3 }'urlmust be public HTTPS without credentials; it is stored encrypted and never returned.handlersare the exactname@versionpairs this endpoint serves;concurrencyis 1–10 requests at a time.projectId+environmentIdrestrict it to one environment, exactly like a scoped worker key. An environment-scoped admin key always creates workers in its own environment.- The response contains the signing
secretonce. Store it as an environment variable of your endpoint. - At most 10 HTTP workers per organization.
GET /api/v1/http-workerslists them,PATCH /api/v1/http-workers/:idwith{ "enabled": false }or{ "concurrency": 5 }changes one,DELETEremoves it.
The worker appears on the Workers page as http-<id> while the platform is dispatching to it.
The request
POST to your URL with Content-Type: application/json, User-Agent: GetRatchet-Workers/1.0 and:
{
"jobId": "…",
"runId": "…",
"stepId": "…",
"tool": { "name": "send_email", "version": "1" },
"input": { "to": "…" },
"attempt": 1,
"idempotencyKey": "…",
"deadline": "2026-10-22T12:00:30.000Z"
}X-GetRatchet-Signature: t=<unix seconds>,v1=<hex> is an HMAC-SHA256 of <t>.<raw body> with your secret — the same scheme as signed alert webhooks. Verify it against the raw body before parsing and reject old timestamps. The request times out at the job's timeout (deadline). Use idempotencyKey for side effects: a timed-out or lost attempt may be sent again.
The response
| Your response | Result |
|---|---|
2xx with JSON { "output": … } (at most 64 KiB) | Step succeeds with output |
2xx with another body, or larger than 64 KiB | Fails, not retried |
408 or 429 | Retried; Retry-After (seconds or date) is honored within the retry policy's bounds |
Other 4xx, or a redirect | Fails, not retried (redirects are never followed) |
5xx, timeout or network error | Retried with the job's retry policy |
Error messages stored on the step contain only the status (for example HTTP worker responded 503), never your URL or response body.
Next.js route handler (Vercel)
// app/api/getratchet/route.ts
import { verifyRatchetSignature } from '@getratchet/sdk';
export async function POST(request: Request) {
const body = await request.text();
const signature = request.headers.get('x-getratchet-signature');
if (!verifyRatchetSignature(body, signature, process.env.GETRATCHET_HTTP_SECRET!, 300))
return new Response('Invalid signature', { status: 401 });
const job = JSON.parse(body);
if (job.tool.name !== 'send_email') return new Response('Unknown tool', { status: 400 });
const id = await sendEmail(job.input, { idempotencyKey: job.idempotencyKey });
return Response.json({ output: { id } });
}Set the route's maxDuration above your job timeout.
AWS Lambda (function URL)
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(body, header, secret, toleranceSec = 300) {
const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header ?? '');
if (!match || Math.abs(Date.now() / 1000 - Number(match[1])) > toleranceSec) return false;
const expected = createHmac('sha256', secret).update(`${match[1]}.${body}`).digest();
return timingSafeEqual(expected, Buffer.from(match[2], 'hex'));
}
export const handler = async (event) => {
const body = event.isBase64Encoded ? Buffer.from(event.body, 'base64').toString() : event.body;
if (!verify(body, event.headers['x-getratchet-signature'], process.env.GETRATCHET_HTTP_SECRET))
return { statusCode: 401, body: 'Invalid signature' };
const job = JSON.parse(body);
const result = await processJob(job.tool, job.input, job.idempotencyKey);
return {
statusCode: 200,
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ output: result }),
};
};Python and Go have the same helper: getratchet.verify_ratchet_signature(body, header, secret) and getratchet.VerifySignature(body, header, secret, 5*time.Minute).
Limits and safety
- Only public addresses are called: every DNS answer is checked (private, loopback, link-local and metadata ranges are refused) and the connection uses the vetted address, so DNS rebinding cannot redirect it.
- Dispatch runs in the GetRatchet maintenance process about once a second while any HTTP worker is enabled (a first new worker is picked up within the maintenance idle interval). Each endpoint gets at most
concurrencyopen requests, and the process caps all open requests together, so a slow endpoint delays only its own jobs. The lease is heartbeated while the request is open. - If the workspace leaves the Pro plan, dispatch pauses; queued jobs stay stored and resume when the plan returns or a polling worker serves the same handlers.
- Rotating the secret means removing the HTTP worker and adding a new one.