REST API & Endpoint Architecture Reference¶
← Back to Home • Deployment Guide • Configuration Reference • Operations
1. How Webhook Processing Works: The Complete Pipeline¶
When an HTTP request hits webhook-async, it passes through a deterministic 10-stage execution pipeline before any command is executed or enqueued:
┌─────────────────────────────────────────┐
│ 1. Match Route & Method │
│ - Path: /{url_prefix}/{hook_id} │
│ - Check hook.http-methods (405) │
└────────────────────┬────────────────────┘
│
┌────────────────────▼────────────────────┐
│ 2. Enforce Size & Content-Type Limits │
│ - Body <= max_body_bytes (413) │
│ - Parse Multipart parts (500) │
└────────────────────┬────────────────────┘
│
┌────────────────────▼────────────────────┐
│ 3. Extract & Parse Payload Data │
│ - Preserve exact raw body bytes │
│ - Parse JSON, XML, or Form data │
│ - Execute parse-parameters-as-json │
└────────────────────┬────────────────────┘
│
┌────────────────────▼────────────────────┐
│ 4. Evaluate Security & Trigger Rules │
│ - Check HMAC signatures (constant- │
│ time equality) │
│ - Check tokens, IP whitelists, regex │
│ - Mismatch -> HTTP 400 (or custom) │
└────────────────────┬────────────────────┘
│
┌────────────────────▼────────────────────┐
│ 5. Build Immutable Execution Snapshot │
│ - Resolve command argv & environment │
│ - Materialize temporary files │
│ - Bind timeout and output limits │
└────────────────────┬────────────────────┘
│
┌───────────────────┴───────────────────┐
│ │
[Sync Hook Branch] [Async Hook Branch]
│ │
┌────────────▼─────────────┐ ┌───────────▼────────────┐
│ 6a. Direct Execution │ │ 6b. Durable Commit │
│ - Spawn tokio::process │ │ - Commit snapshot to │
│ - Bound stdout/stderr │ │ SQLite / Redis │
│ - Clean up temp files │ │ - Dedup Idempotency │
│ - Return HTTP 200/500 │ │ - Return HTTP 202 │
└──────────────────────────┘ └────────────────────────┘
2. Webhook Receiver Endpoints¶
1. Root Liveness Ping¶
GET /
Used by network load balancers, Kubernetes liveness probes, and reverse proxies.
- Authentication: None required.
- Response: 200 OK with plain text "OK".
- Headers: Includes global response_headers configured in config.toml.
2. Trigger a Webhook¶
POST /{url_prefix}/{hook_id}
Executes the hook identified by {hook_id}.
- If url_prefix is configured as "hooks" (the default), the path is /hooks/my-hook.
- If url_prefix is empty (""), the path is /my-hook.
- Subpaths are fully supported if your hook ID contains forward slashes (e.g. /hooks/deploy/prod/backend).
Supported Request Headers¶
| Header | Description |
|---|---|
Content-Type |
application/json, application/x-www-form-urlencoded, text/xml, or multipart/form-data. |
Idempotency-Key / X-Idempotency-Key |
(Async hooks only) Unique request identifier. Prevents duplicate execution if a client retries due to network failure. |
X-Request-Id |
Distributed tracing request ID. Propagated through execution logs and responses. |
Exhaustive Response Status Codes¶
| HTTP Status | Condition | Response Body |
|---|---|---|
200 OK |
Synchronous hook executed successfully. | Output from stdout/stderr (if include-command-output-in-response: true), or the configured response-message. |
202 Accepted |
Asynchronous hook validated and committed to durable storage queue. | {"job_id": "...", "status": "queued", "message": "..."} |
400 Bad Request |
Trigger rules were not satisfied (HMAC mismatch, missing parameter, regex failure). | "Hook rules were not satisfied." (or custom status code configured via trigger-rule-mismatch-http-response-code) |
405 Method Not Allowed |
Incoming HTTP verb (e.g. GET) is not in the hook's http-methods list. |
Empty body. |
413 Payload Too Large |
Request body size exceeds server.max_body_bytes. |
"Request body too large." |
429 Too Many Requests |
Async queue capacity full (queue.max_pending_jobs reached). |
{"error": "Queue capacity full."} |
500 Internal Server Error |
Trigger rule evaluation failure, multipart parsing failure, or command exited with non-zero status. | "Error occurred while evaluating hook rules." or command stderr output. |
503 Service Unavailable |
In async mode, storage backend is unreachable. The hook was not acknowledged and must be retried by the caller. | {"error": "Queue backend unavailable."} |
3. System Diagnostic & OpenAPI Endpoints¶
These endpoints provide health monitoring and schema inspection without requiring authentication.
1. Basic Health Check¶
GET /api/v1/health
Reports service availability and compiled application version.
curl -s http://localhost:9000/api/v1/health
{
"status": "ok",
"version": "0.1.0"
}
2. Storage Readiness Probe¶
GET /api/v1/ready
Performs an active ping against the configured storage backend (e.g. SELECT 1 on SQLite or PING on Valkey/Redis).
curl -s http://localhost:9000/api/v1/ready
{
"status": "ready",
"storage": "connected"
}
If storage is disconnected, returns 503 Service Unavailable with {"status": "not_ready", "error": "..."}.
3. OpenAPI 3.1 Specification¶
GET /api/v1/openapi.json
Returns the complete machine-readable OpenAPI 3.1 specification describing all REST endpoints, request schemas, response models, and authentication requirements.
curl -s http://localhost:9000/api/v1/openapi.json | jq .
4. Administrative REST API (/api/v1/*)¶
All administrative endpoints require Bearer token authentication configured via [auth].admin_token, [auth].admin_token_env, or [auth].admin_token_file.
Authorization: Bearer <YOUR_ADMIN_TOKEN>
Security Guardrails: - If no admin token is configured in
config.toml, all administrative endpoints return503 Service Unavailable("Admin token not configured"). Unauthenticated administrative access is strictly disallowed by default. - Rate limited to 60 requests/minute per token. Exceeding limits returns429 Too Many RequestswithRetry-After: 60.
1. Get Queue Statistics¶
GET /api/v1/stats
Returns real-time job counts partitioned across all 8 canonical job states.
curl -s -H "Authorization: Bearer $WEBHOOK_ADMIN_TOKEN" \
http://localhost:9000/api/v1/stats
{
"counts_by_state": {
"queued": 0,
"running": 1,
"retry_wait": 0,
"succeeded": 412,
"failed": 2,
"cancel_requested": 0,
"cancelled": 1,
"dead_letter": 0
},
"pending_count": 1
}
2. List & Filter Jobs¶
GET /api/v1/jobs?state={state}&hook_id={id}&limit={n}&offset={n}
Query Parameters¶
| Parameter | Type | Default | Description |
|---|---|---|---|
state |
string | (optional) | Filter by state: queued, running, retry_wait, succeeded, failed, cancel_requested, cancelled, dead_letter. |
hook_id |
string | (optional) | Filter by hook identifier. |
limit |
integer | 50 |
Number of records to return (1 to 500). |
offset |
integer | 0 |
Pagination offset. |
curl -s -H "Authorization: Bearer $WEBHOOK_ADMIN_TOKEN" \
"http://localhost:9000/api/v1/jobs?state=failed&limit=10"
{
"items": [
{
"id": "018d9f10-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
"hook_id": "deploy-app",
"state": "failed",
"priority": 0,
"attempt": 5,
"max_attempts": 5,
"created_at": "2026-03-29T10:15:30.123456789Z",
"started_at": "2026-03-29T10:15:31.000000000Z",
"completed_at": "2026-03-29T10:16:05.000000000Z",
"worker_id": "worker-prod-1:4192",
"exit_code": 1,
"error_class": "transient",
"error_summary": "Process exited with status: exit status: 1"
}
],
"total": 1,
"limit": 10,
"offset": 0
}
3. Get Job Details & Execution History¶
GET /api/v1/jobs/{job_id}
Returns complete metadata, immutable execution snapshot parameters, and the full audit trail of all execution attempts (including captured stdout and stderr previews).
curl -s -H "Authorization: Bearer $WEBHOOK_ADMIN_TOKEN" \
http://localhost:9000/api/v1/jobs/018d9f10-1a2b-7c3d-8e4f-5a6b7c8d9e0f
{
"job": {
"id": "018d9f10-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
"hook_id": "deploy-app",
"state": "succeeded",
"priority": 0,
"attempt": 1,
"max_attempts": 5,
"created_at": "2026-03-29T10:15:30.123456789Z",
"started_at": "2026-03-29T10:15:31.000000000Z",
"completed_at": "2026-03-29T10:15:45.000000000Z",
"worker_id": "worker-prod-1:4192",
"exit_code": 0
},
"attempts": [
{
"job_id": "018d9f10-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
"attempt": 1,
"worker_id": "worker-prod-1:4192",
"started_at": "2026-03-29T10:15:31.000000000Z",
"finished_at": "2026-03-29T10:15:45.000000000Z",
"exit_code": 0,
"stdout_preview": "Deploying release v1.4.2...\nMigration complete.\nService restarted.",
"stderr_preview": ""
}
]
}
4. Retry a Job¶
POST /api/v1/jobs/{job_id}/retry
Manually re-enqueues a job that ended in failed or dead_letter state.
- Resets the job to queued state.
- Automatically increments max_attempts so the job is eligible for immediate execution.
- Returns 409 Conflict if the job is already active (running or queued).
curl -X POST -s -H "Authorization: Bearer $WEBHOOK_ADMIN_TOKEN" \
http://localhost:9000/api/v1/jobs/018d9f10-1a2b-7c3d-8e4f-5a6b7c8d9e0f/retry
5. Cancel a Job¶
POST /api/v1/jobs/{job_id}/cancel
Cancels a job:
- If queued or retry_wait: Transitions immediately to cancelled.
- If running: Transitions to cancel_requested. The active worker's heartbeat loop detects this state within milliseconds, sends SIGKILL to the child process group (-pgid), cleans up temporary files, and marks the job as cancelled.
curl -X POST -s -H "Authorization: Bearer $WEBHOOK_ADMIN_TOKEN" \
http://localhost:9000/api/v1/jobs/018d9f10-1a2b-7c3d-8e4f-5a6b7c8d9e0f/cancel
6. Inspect Active Hooks (Secrets Redacted)¶
GET /api/v1/hooks
Returns a list of all loaded hook definitions. Sensitive parameters (HMAC keys, bearer tokens) are safely redacted.
curl -s -H "Authorization: Bearer $WEBHOOK_ADMIN_TOKEN" \
http://localhost:9000/api/v1/hooks
7. Inspect Active Workers¶
GET /api/v1/workers
Returns all background workers currently heartbeating into the cluster.
curl -s -H "Authorization: Bearer $WEBHOOK_ADMIN_TOKEN" \
http://localhost:9000/api/v1/workers
[
{
"worker_id": "worker-prod-1:4192",
"host": "ip-10-0-1-15.internal",
"concurrency": 8,
"active_jobs": 2,
"completed_count": 894,
"failed_count": 3,
"draining": false,
"last_heartbeat_at": "2026-03-29T10:20:00.000000000Z"
}
]
8. Storage Engine Status & Capabilities¶
GET /api/v1/storage/status
Returns backend engine type, multi-host capabilities, and connection status.
curl -s -H "Authorization: Bearer $WEBHOOK_ADMIN_TOKEN" \
http://localhost:9000/api/v1/storage/status
{
"backend": "sqlite",
"connected": true,
"capabilities": {
"backend": "sqlite",
"supports_priority": true,
"supports_multi_host": false,
"supports_idempotency": true
}
}
9. Real-Time Server-Sent Events (SSE) Stream¶
GET /api/v1/events
Streams live JSON snapshots of queue metrics and active jobs every 2 seconds. Used by monitoring tools and the built-in Web management UI.
curl -N -s -H "Authorization: Bearer $WEBHOOK_ADMIN_TOKEN" \
http://localhost:9000/api/v1/events
event: stats
data: {"counts_by_state":{"queued":0,"running":1,"succeeded":412},"pending_count":1}
event: stats
data: {"counts_by_state":{"queued":0,"running":0,"succeeded":413},"pending_count":0}