Webhooks & the execution endpoint

Weev delivers work to your service the same shape as any webhook: an authenticated POST to the endpoint that createWeevMiddleware mounts. The endpoint only accepts the offer — outcomes travel back over authenticated callbacks, never in the offer response.

Cloud → your service

The offer

POST {endpoint}/.weev/run, authenticated with Authorization: Bearer <wvout_ key> — the environment's outbound key, verified timing-safely by the SDK when runToken is configured. Redirects are never followed. Protocol version: 2.

jobRunId

The logical run being offered.

attemptId

The specific attempt in the ledger.

jobName

Registry lookup key — must match a registered weev.job().

batchRunId / jobId

The enclosing batch run and the job's identity.

executionToken

Single-use token, rotated per dispatch; presented back on every callback.

protocolVersion

Currently 2. The SDK rejects versions it does not support.

Response body (every status)json

{ "status": "accepted" | "busy" | "not_found" | "error", "jobRunId", "message"? }

202acceptedOffer accepted; execution proceeds asynchronously. Duplicates of an active or recently completed run also answer 202.

429busyThe service is at its concurrency limit (default 50). Weev retries the dispatch.

404not_foundThe job name is not in this process's registry.

400 / 401errorMalformed offer, unsupported protocol version, or a missing/wrong bearer when runToken is configured.

5xxerrorUnexpected SDK error. Weev retries, then marks the dispatch exhausted.

Note

Fast-ack contract

The offer response says only whether the offer was accepted. Success and failure are reported through the callbacks below — a 202 never implies the job succeeded.

Your service → Cloud

The three callbacks

All three are authenticated with Authorization: Bearer <wvin_ key> — the environment's inbound key (the SDK's token) — and every one carries the single-use executionToken from the offer.

Claim

POST /v1/job-runs/:jobRunId/start

Sent before any handler code runs. Grants a fenced lease with an expiry and heartbeat interval; a 409 means another claimant owns the attempt and the SDK drops the offer silently.

Heartbeat

POST /v1/job-runs/:jobRunId/heartbeat

Renews the lease on an interval (default 30s) and carries the execution phase. The response can revoke the lease or request cancellation, which aborts ctx.signal.

Complete

POST /v1/job-runs/:jobRunId/complete

Reports success (with an optional JSON-serializable result) or failure (with an error). A lost success response is retried for up to 15 minutes and never converted into a failure.

The claim takes a fenced lease: a second claimant, an overlapping retry, or a late callback cannot execute or commit the same attempt twice. The security properties of this handshake are laid out on the Security & Architecture page.