Webhooks
POST /api/v1/webhooks. Each event is signed with your endpoint's secret, retried until your endpoint answers 2xx, logged, and can be sent again.settlement.job_created
A job was created from your Work Spec.
data: job
settlement.executor_attached
Steps were given to an executor.
data: job, executor
settlement.executor_verified
An executor's pay account is ready, so their pay can go out.
data: executor
settlement.step_pending
The Oracle is waiting on evidence that is still due, such as a reading or an inspection.
data: job, step
settlement.step_review
The Oracle couldn't decide on its own, so a person at 4 Seasons is checking the proof.
data: job, step
settlement.step_verified
The step is verified. Its release is made next.
data: job, step
settlement.step_rejected
The proof was sent back. Send new proof for the step.
data: job, step
settlement.release_sent
The step's pay left over the rail.
data: release
settlement.release_held
A release is waiting, with the reason: funding, the executor's pay account or the live switch.
data: release
settlement.job_completed
Every step on the job is verified.
data: job
settlement.lien_waiver_signed
An executor signed a lien waiver in your app.
data: waiver
settlement.capacity_reserved
Hours were reserved for you. They are held until the lapse time.
data: reservation
settlement.capacity_converted
A reservation was attached to a job. The hours stay on the pros' calendars for it.
data: reservation
settlement.capacity_released
A reservation was released by you, or it lapsed because no job was attached in time. The reason says which.
data: reservation
settlement.capacity_refilled
A pro pulled out, didn't confirm or didn't come, and another qualified pro took every hour they held. The message says what happened.
data: reservation, message
settlement.capacity_short
A pro pulled out, didn't confirm or didn't come, and some or all of their hours could not be refilled. The message says how many are still held.
data: reservation, message
settlement.step_verified from the sandbox, signed with the sample secret whsec_example_only_never_real_00000000. Check the signature over the raw body, byte for byte, before you parse it.Headers
{"id":"evt_example_step_verified","type":"settlement.step_verified","created":"2026-11-10T15:00:00.000Z","data":{"job":{"id":"fb8fdaf4-d498-4a9f-a3ff-a5767503c907","loan":null,"site":{"zip":"30306","city":"Atlanta","state":"GA","county":"Fulton","address":"1180 Sample Ave NE"},"owner":{"name":"Sample Homeowner"},"steps":[{"id":"3e697db8-5927-4893-a87c-35f0ab27fcde","key":"fix","seq":1,"name":"Find and repair the leak","rounds":1,"status":"verified","release":null,"verdict":{"at":"2026-11-10T14:04:00.000Z","reasons":["waiting on photo checks"],"verdict":"accept","decidedBy":"human","waitingOn":["Waiting on evidence"],"confidence":0,"ruleVersion":"oracle-1/task.leak-repair@1/r1"},"stepKind":{"id":"task.leak-repair","version":1},"proofPlan":[{"shot":"leak-before","label":"Where the water was coming from"},{"shot":"leak-after","label":"The repair, dry"}],"executorId":"844df2fc-9526-4633-ac1f-779e47281496","verifiedAt":"2026-11-10T14:04:00.000Z","payoutCents":20000,"measurements":[]},{"id":"46096d88-9562-400c-a506-21e937630643","key":"inspect","seq":2,"name":"Final inspection","rounds":0,"status":"open","release":null,"verdict":null,"stepKind":{"id":"inspection.final-building","version":1},"proofPlan":[{"shot":"result-card","label":"Inspection card or result"}],"executorId":"844df2fc-9526-4633-ac1f-779e47281496","verifiedAt":null,"payoutCents":7500,"measurements":[]}],"title":"Leak under the kitchen sink","family":"repair.leak","number":"SJ-1001","object":"settlement_job","status":"open","livemode":false,"createdAt":"2026-11-10T14:23:00.000Z","reference":"CLAIM-881","completedAt":null},"step":{"id":"3e697db8-5927-4893-a87c-35f0ab27fcde","key":"fix","seq":1,"name":"Find and repair the leak","rounds":1,"status":"verified","release":null,"verdict":{"at":"2026-11-10T14:04:00.000Z","reasons":["waiting on photo checks"],"verdict":"accept","decidedBy":"human","waitingOn":["Waiting on evidence"],"confidence":0,"ruleVersion":"oracle-1/task.leak-repair@1/r1"},"stepKind":{"id":"task.leak-repair","version":1},"proofPlan":[{"shot":"leak-before","label":"Where the water was coming from"},{"shot":"leak-after","label":"The repair, dry"}],"executorId":"844df2fc-9526-4633-ac1f-779e47281496","verifiedAt":"2026-11-10T14:04:00.000Z","payoutCents":20000,"measurements":[]}},"livemode":false}{
"id": "evt_example_step_verified",
"type": "settlement.step_verified",
"created": "2026-11-10T15:00:00.000Z",
"data": {
"job": {
"id": "fb8fdaf4-d498-4a9f-a3ff-a5767503c907",
"loan": null,
"site": {
"zip": "30306",
"city": "Atlanta",
"state": "GA",
"county": "Fulton",
"address": "1180 Sample Ave NE"
},
"owner": {
"name": "Sample Homeowner"
},
"steps": [
{
"id": "3e697db8-5927-4893-a87c-35f0ab27fcde",
"key": "fix",
"seq": 1,
"name": "Find and repair the leak",
"rounds": 1,
"status": "verified",
"release": null,
"verdict": {
"at": "2026-11-10T14:04:00.000Z",
"reasons": [
"waiting on photo checks"
],
"verdict": "accept",
"decidedBy": "human",
"waitingOn": [
"Waiting on evidence"
],
"confidence": 0,
"ruleVersion": "oracle-1/task.leak-repair@1/r1"
},
"stepKind": {
"id": "task.leak-repair",
"version": 1
},
"proofPlan": [
{
"shot": "leak-before",
"label": "Where the water was coming from"
},
{
"shot": "leak-after",
"label": "The repair, dry"
}
],
"executorId": "844df2fc-9526-4633-ac1f-779e47281496",
"verifiedAt": "2026-11-10T14:04:00.000Z",
"payoutCents": 20000,
"measurements": []
},
{
"id": "46096d88-9562-400c-a506-21e937630643",
"key": "inspect",
"seq": 2,
"name": "Final inspection",
"rounds": 0,
"status": "open",
"release": null,
"verdict": null,
"stepKind": {
"id": "inspection.final-building",
"version": 1
},
"proofPlan": [
{
"shot": "result-card",
"label": "Inspection card or result"
}
],
"executorId": "844df2fc-9526-4633-ac1f-779e47281496",
"verifiedAt": null,
"payoutCents": 7500,
"measurements": []
}
],
"title": "Leak under the kitchen sink",
"family": "repair.leak",
"number": "SJ-1001",
"object": "settlement_job",
"status": "open",
"livemode": false,
"createdAt": "2026-11-10T14:23:00.000Z",
"reference": "CLAIM-881",
"completedAt": null
},
"step": {
"id": "3e697db8-5927-4893-a87c-35f0ab27fcde",
"key": "fix",
"seq": 1,
"name": "Find and repair the leak",
"rounds": 1,
"status": "verified",
"release": null,
"verdict": {
"at": "2026-11-10T14:04:00.000Z",
"reasons": [
"waiting on photo checks"
],
"verdict": "accept",
"decidedBy": "human",
"waitingOn": [
"Waiting on evidence"
],
"confidence": 0,
"ruleVersion": "oracle-1/task.leak-repair@1/r1"
},
"stepKind": {
"id": "task.leak-repair",
"version": 1
},
"proofPlan": [
{
"shot": "leak-before",
"label": "Where the water was coming from"
},
{
"shot": "leak-after",
"label": "The repair, dry"
}
],
"executorId": "844df2fc-9526-4633-ac1f-779e47281496",
"verifiedAt": "2026-11-10T14:04:00.000Z",
"payoutCents": 20000,
"measurements": []
}
},
"livemode": false
}4s-signature is t=<unix>,v1=<hex>, an HMAC-SHA256 of t.body with your secret. Refuse a timestamp more than five minutes old, compare in constant time, and accept any v1 that matches: while a secret rotates there are two.import { createHmac, timingSafeEqual } from "node:crypto";
// header: the 4s-signature request header. body: the raw request body, as received.
export function verify4s(secret: string, body: string, header: string, toleranceSec = 300): boolean {
const parts = header.split(",").map((p) => p.split("=") as [string, string]);
const t = Number(parts.find(([k]) => k === "t")?.[1]);
if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest();
// During a secret rotation there are two v1 values: either one is enough.
return parts.some(([k, v]) => k === "v1" && v.length === 64 && timingSafeEqual(Buffer.from(v, "hex"), expected));
}Anything but a 2xx is tried again with exponential backoff, eight tries in all. 4s-webhook-id is the event id on every try and every replay: keep the first and drop the rest.
POST /api/v1/webhooks/deliveries/{id}/replay: the same event id and body as a new delivery, up to 20 times per event.POST /api/v1/webhooks/{id}/rotate-secret returns a new secret once. For the grace period you choose (up to 72 hours) each delivery carries a second v1 signed with the old secret, so you can switch without missing an event.GET /api/v1/webhooks/deliveries, or Developers in your dashboard.livemode.