API Reference
REST API reference for the Approval Workflow Engine — rendered directly from the live OpenAPI 3.1 spec committed to the repo.
Base path: /v1/awe/. The spec below is rendered from the live docs/openapi.json. CI regenerates it from the FastAPI app on every src/-touching push, so endpoint signatures, response shapes, status-code descriptions, and the error-code catalog stay in lockstep with the code. This page does not duplicate any of that in prose.
A running instance also exposes the live spec at /v1/awe/openapi.json and interactive UIs at /v1/awe/docs (Swagger) and /v1/awe/redoc.
Caller API surface — what an integrator actually uses
The full reference below covers every endpoint, including the admin surface that powers AWE's own portal (policy CRUD, simulate, delegations, audit log, delivery retry). Caller services do not call any of those.
A Caller integration touches only the five endpoints below, plus implements one inbound webhook handler.
Outbound — Caller → AWE
POST /v1/awe/requests
A Caller-owned artifact has been created and needs approval. Pass policy_key, artifact_type, artifact_id, context, callback_url, requester.
POST /v1/awe/requests/{id}/cancel
The underlying artifact was withdrawn, or the Caller wants to abort an in-flight flow.
GET /v1/awe/tasks?assignee=me (forwarding the approver's JWT)
When an approver opens the Caller's UI — returns every open AWE task assigned to the user whose JWT is on the request, across all requests and policies. me expands to the token's sub claim. The Caller joins this list with its own artifact rows (by awe_request_id) to build the per-Caller inbox.
POST /v1/awe/tasks/{task_id}/decision (forwarding the approver's JWT)
Records the approver's approve / reject / abstain.
GET /v1/awe/requests/{id} (optional)
Per-request lookup — full state of one approval flow by id (current stage, resolved approvers, history, context snapshot). Used when a user opens an artifact detail page in the Caller's UI and the Caller wants to render an "approval state" panel inline. Not an admin list view; takes a single id, returns one request. Skip it if you'd rather rely solely on the webhook to drive UI state. The Caller decides which users see this panel — AWE itself does not restrict reads.
Inbound — AWE → Caller (implemented by the Caller, not called)
POST {callback_url}
Receives signed AWE webhooks. On request_approved apply the artifact-side effect; on request_rejected / request_cancelled close out the artifact accordingly. Validate the X-Approval-Signature HMAC, dedup on X-Approval-Event-Id, return 2xx within the configured timeout.
Everything else in the reference below is admin / operator surface served from AWE's bundled portal.
Error responses
Every non-2xx response returns AWE's standard error envelope with an AWE-NNN code in errors[0].errorCode. See the Error codes page for the full catalog — what each code means, the HTTP status it ships with, and whether to retry.
Service is ready.
openg2p.aweExample: openg2p.awe1.0Example: 1.02026-04-23T10:00:00.000ZHealth probe failed to reach the database.
GET /v1/awe/health HTTP/1.1
Accept: */*
{
"id": "openg2p.awe",
"version": "1.0",
"responsetime": "2026-04-23T10:00:00.000Z",
"response": {
"status": "UP"
},
"errors": [
{
"errorCode": "AWE-003",
"message": "Approval request not found"
}
]
}Successful Response
openg2p.aweExample: openg2p.awe1.0Example: 1.02026-04-23T10:00:00.000ZGET /v1/awe/version HTTP/1.1
Accept: */*
Successful Response
{
"id": "openg2p.awe",
"version": "1.0",
"responsetime": "2026-04-23T10:00:00.000Z",
"response": {
"service_version": "0.1.0",
"build_time": "2026-04-23T08:30:00.000Z",
"git_commit": "a1b2c3d"
},
"errors": [
{
"errorCode": "AWE-003",
"message": "Approval request not found"
}
]
}registry.change_request.v1Registry CR approvalregistry.change_requestFilter the request's requester out of every stage's approver list.
falseFilter users who approved an earlier stage out of later stages.
falseSuccessful Response
falsefalseBearer token missing, malformed, or fails signature/expiry checks.
Token is valid but lacks the AWE_ADMIN role required for this mutation.
Policy version conflict — typically a duplicate policy_key on create, or attempting to edit/activate a version in the wrong status.
Validation Error
POST /v1/awe/policies HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 628
{
"policy_key": "registry.change_request.v1",
"name": "Registry CR approval",
"description": "text",
"artifact_type": "registry.change_request",
"forbid_self_approval": false,
"forbid_repeat_approvers": false,
"stages": [
{
"name": "District officers",
"stage_order": 1,
"mode": "any-n",
"mode_value": 1,
"sla_hours": 1,
"skip_if": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"on_empty": "block",
"parallel_group": 1,
"on_breach": "text",
"escalation_rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false
}
],
"rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false
}
]
}
]
}{
"id": "text",
"policy_key": "text",
"version": 1,
"name": "text",
"description": "text",
"status": "text",
"artifact_type": "text",
"forbid_self_approval": false,
"forbid_repeat_approvers": false,
"created_by": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"stages": [
{
"name": "District officers",
"stage_order": 1,
"mode": "any-n",
"mode_value": 1,
"sla_hours": 1,
"skip_if": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"on_empty": "block",
"parallel_group": 1,
"on_breach": "text",
"escalation_rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false,
"id": "text"
}
],
"rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false,
"id": "text"
}
],
"id": "text"
}
]
}Successful Response
falsefalseBearer token missing, malformed, or fails signature/expiry checks.
Token is valid but lacks AWE_VIEWER or AWE_ADMIN role.
GET /v1/awe/policies HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"id": "text",
"policy_key": "text",
"version": 1,
"name": "text",
"description": "text",
"status": "text",
"artifact_type": "text",
"forbid_self_approval": false,
"forbid_repeat_approvers": false,
"created_by": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"stages": [
{
"name": "District officers",
"stage_order": 1,
"mode": "any-n",
"mode_value": 1,
"sla_hours": 1,
"skip_if": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"on_empty": "block",
"parallel_group": 1,
"on_breach": "text",
"escalation_rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false,
"id": "text"
}
],
"rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false,
"id": "text"
}
],
"id": "text"
}
]
}
]Successful Response
Bearer token missing, malformed, or fails signature/expiry checks.
Token is valid but lacks AWE_VIEWER or AWE_ADMIN role.
No matching policy / policy version exists.
Validation Error
GET /v1/awe/policies/{policy_key}/versions HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"id": "text",
"policy_key": "text",
"version": 1,
"status": "text",
"created_at": "2026-01-01T00:00:00.000Z"
}
]Successful Response
falsefalseBearer token missing, malformed, or fails signature/expiry checks.
Token is valid but lacks AWE_VIEWER or AWE_ADMIN role.
No matching policy / policy version exists.
Validation Error
GET /v1/awe/policies/{policy_key}/versions/{version} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "text",
"policy_key": "text",
"version": 1,
"name": "text",
"description": "text",
"status": "text",
"artifact_type": "text",
"forbid_self_approval": false,
"forbid_repeat_approvers": false,
"created_by": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"stages": [
{
"name": "District officers",
"stage_order": 1,
"mode": "any-n",
"mode_value": 1,
"sla_hours": 1,
"skip_if": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"on_empty": "block",
"parallel_group": 1,
"on_breach": "text",
"escalation_rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false,
"id": "text"
}
],
"rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false,
"id": "text"
}
],
"id": "text"
}
]
}registry.change_request.v1Registry CR approvalregistry.change_requestFilter the request's requester out of every stage's approver list.
falseFilter users who approved an earlier stage out of later stages.
falseSuccessful Response
falsefalsePolicy body violates a structural rule (e.g. URL/body key mismatch).
Bearer token missing, malformed, or fails signature/expiry checks.
Token is valid but lacks the AWE_ADMIN role required for this mutation.
No matching policy / policy version exists.
Resource is in a state that disallows this transition. Examples: request is already in a terminal state (approved/rejected/cancelled); task is not open/claimed; policy version is not draft for editing; delivery has already succeeded.
Validation Error
PATCH /v1/awe/policies/{policy_key}/versions/{version} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 628
{
"policy_key": "registry.change_request.v1",
"name": "Registry CR approval",
"description": "text",
"artifact_type": "registry.change_request",
"forbid_self_approval": false,
"forbid_repeat_approvers": false,
"stages": [
{
"name": "District officers",
"stage_order": 1,
"mode": "any-n",
"mode_value": 1,
"sla_hours": 1,
"skip_if": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"on_empty": "block",
"parallel_group": 1,
"on_breach": "text",
"escalation_rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false
}
],
"rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false
}
]
}
]
}{
"id": "text",
"policy_key": "text",
"version": 1,
"name": "text",
"description": "text",
"status": "text",
"artifact_type": "text",
"forbid_self_approval": false,
"forbid_repeat_approvers": false,
"created_by": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"stages": [
{
"name": "District officers",
"stage_order": 1,
"mode": "any-n",
"mode_value": 1,
"sla_hours": 1,
"skip_if": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"on_empty": "block",
"parallel_group": 1,
"on_breach": "text",
"escalation_rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false,
"id": "text"
}
],
"rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false,
"id": "text"
}
],
"id": "text"
}
]
}Successful Response
falsefalseBearer token missing, malformed, or fails signature/expiry checks.
Token is valid but lacks the AWE_ADMIN role required for this mutation.
No matching policy / policy version exists.
Validation Error
POST /v1/awe/policies/{policy_key}/versions/{version}/activate HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "text",
"policy_key": "text",
"version": 1,
"name": "text",
"description": "text",
"status": "text",
"artifact_type": "text",
"forbid_self_approval": false,
"forbid_repeat_approvers": false,
"created_by": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"stages": [
{
"name": "District officers",
"stage_order": 1,
"mode": "any-n",
"mode_value": 1,
"sla_hours": 1,
"skip_if": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"on_empty": "block",
"parallel_group": 1,
"on_breach": "text",
"escalation_rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false,
"id": "text"
}
],
"rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false,
"id": "text"
}
],
"id": "text"
}
]
}registry.change_request.v1Registry CR approvalregistry.change_requestFilter the request's requester out of every stage's approver list.
falseFilter users who approved an earlier stage out of later stages.
falseSuccessful Response
falsefalsePolicy body violates a structural rule (e.g. URL/body key mismatch).
Bearer token missing, malformed, or fails signature/expiry checks.
Token is valid but lacks the AWE_ADMIN role required for this mutation.
No matching policy / policy version exists.
Validation Error
PUT /v1/awe/policies/{policy_key} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 628
{
"policy_key": "registry.change_request.v1",
"name": "Registry CR approval",
"description": "text",
"artifact_type": "registry.change_request",
"forbid_self_approval": false,
"forbid_repeat_approvers": false,
"stages": [
{
"name": "District officers",
"stage_order": 1,
"mode": "any-n",
"mode_value": 1,
"sla_hours": 1,
"skip_if": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"on_empty": "block",
"parallel_group": 1,
"on_breach": "text",
"escalation_rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false
}
],
"rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false
}
]
}
]
}{
"id": "text",
"policy_key": "text",
"version": 1,
"name": "text",
"description": "text",
"status": "text",
"artifact_type": "text",
"forbid_self_approval": false,
"forbid_repeat_approvers": false,
"created_by": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"stages": [
{
"name": "District officers",
"stage_order": 1,
"mode": "any-n",
"mode_value": 1,
"sla_hours": 1,
"skip_if": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"on_empty": "block",
"parallel_group": 1,
"on_breach": "text",
"escalation_rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false,
"id": "text"
}
],
"rules": [
{
"rule_type": "role",
"rule_value": {
"role": "district-officer"
},
"kind": "approver",
"required": false,
"id": "text"
}
],
"id": "text"
}
]
}50Successful Response
Bearer token missing, malformed, or fails signature/expiry checks.
Validation Error
GET /v1/awe/requests HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"id": "text",
"policy_id": "text",
"policy_key": "text",
"policy_version": 1,
"artifact_type": "text",
"artifact_id": "text",
"source_service": "text",
"requester": "text",
"context": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"status": "text",
"current_stage_order": 1,
"callback_url": "text",
"completed_at": "2026-01-01T00:00:00.000Z",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
]Successful Response
Bearer token missing, malformed, or fails signature/expiry checks.
Token is valid but lacks AWE_VIEWER or AWE_ADMIN role.
No matching policy / policy version exists.
Validation Error
An approver-resolution rule's upstream call failed (Keycloak admin API, HTTP resolver, etc.).
POST /v1/awe/policies/{policy_key}/versions/{version}/simulate HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 44
{
"context": {
"amount": 15000,
"district": "D1"
}
}{
"policy_id": "text",
"policy_version": 1,
"stages": [
{
"stage_order": 1,
"name": "text",
"mode": "text",
"mode_value": 1,
"resolved_approvers": [
"text"
],
"skipped": false,
"skip_reason": "text"
}
]
}registry.change_request.v1registry.change_requestcr-42https://registry/internal/approval-callbacksu-aliceSuccessful Response
Engine refused to start the request (e.g. malformed context).
Bearer token missing, malformed, or fails signature/expiry checks.
Policy key has no version in active status — no flow can be started for it.
Validation Error
POST /v1/awe/requests HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 262
{
"policy_key": "registry.change_request.v1",
"artifact_type": "registry.change_request",
"artifact_id": "cr-42",
"context": {
"amount": 15000,
"district": "D1"
},
"callback_url": "https://registry/internal/approval-callbacks",
"callback_secret_id": "text",
"requester": "u-alice"
}{
"request_id": "text",
"status": "text",
"current_stage_order": 1,
"tasks": [
{
"id": "text",
"request_id": "text",
"stage_id": "text",
"stage_order": 1,
"assignee": "text",
"assignee_name": "text",
"kind": "approver",
"delegated_from": "text",
"reassigned_from": "text",
"status": "text",
"claimed_at": "2026-01-01T00:00:00.000Z",
"completed_at": "2026-01-01T00:00:00.000Z",
"due_at": "2026-01-01T00:00:00.000Z",
"decision_id": "text",
"decision_action": "text",
"decision_comment": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"context": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"artifact_type": "text",
"artifact_id": "text",
"policy_key": "text",
"search_text": "text"
}
]
}Successful Response
Bearer token missing, malformed, or fails signature/expiry checks.
No approval request with the given id.
Validation Error
GET /v1/awe/requests/{request_id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "text",
"policy_id": "text",
"policy_key": "text",
"policy_version": 1,
"artifact_type": "text",
"artifact_id": "text",
"source_service": "text",
"requester": "text",
"context": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"status": "text",
"current_stage_order": 1,
"callback_url": "text",
"completed_at": "2026-01-01T00:00:00.000Z",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}Successful Response
Bearer token missing, malformed, or fails signature/expiry checks.
Token is valid but lacks the AWE_ADMIN role required for this mutation.
No approval request with the given id.
Resource is in a state that disallows this transition. Examples: request is already in a terminal state (approved/rejected/cancelled); task is not open/claimed; policy version is not draft for editing; delivery has already succeeded.
Validation Error
POST /v1/awe/requests/{request_id}/cancel HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 32
{
"reason": "text",
"actor": "text"
}{
"id": "text",
"policy_id": "text",
"policy_key": "text",
"policy_version": 1,
"artifact_type": "text",
"artifact_id": "text",
"source_service": "text",
"requester": "text",
"context": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"status": "text",
"current_stage_order": 1,
"callback_url": "text",
"completed_at": "2026-01-01T00:00:00.000Z",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}Successful Response
Bearer token missing, malformed, or fails signature/expiry checks.
Validation Error
GET /v1/awe/requests/{request_id}/events HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"id": "text",
"request_id": "text",
"event_type": "text",
"payload": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"created_at": "2026-01-01T00:00:00.000Z"
}
]Filter by assignee. Default me resolves to preferred_username, then username, then sub. Pass * (or any non-me value) plus request_id to enumerate all tasks for a given request — used by the admin Request Detail page.
meCase-insensitive substring match against task search_text.
125Successful Response
Bearer token missing, malformed, or fails signature/expiry checks.
Validation Error
GET /v1/awe/tasks HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"id": "text",
"request_id": "text",
"stage_id": "text",
"stage_order": 1,
"assignee": "text",
"assignee_name": "text",
"kind": "approver",
"delegated_from": "text",
"reassigned_from": "text",
"status": "text",
"claimed_at": "2026-01-01T00:00:00.000Z",
"completed_at": "2026-01-01T00:00:00.000Z",
"due_at": "2026-01-01T00:00:00.000Z",
"decision_id": "text",
"decision_action": "text",
"decision_comment": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"context": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"artifact_type": "text",
"artifact_id": "text",
"policy_key": "text",
"search_text": "text"
}
],
"total": 1,
"page": 1,
"page_size": 1,
"pages": 1
}Successful Response
approverBearer token missing, malformed, or fails signature/expiry checks.
Task is not assigned to the caller and the caller is not an admin.
No task with the given id.
Resource is in a state that disallows this transition. Examples: request is already in a terminal state (approved/rejected/cancelled); task is not open/claimed; policy version is not draft for editing; delivery has already succeeded.
Validation Error
POST /v1/awe/tasks/{task_id}/claim HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "text",
"request_id": "text",
"stage_id": "text",
"stage_order": 1,
"assignee": "text",
"assignee_name": "text",
"kind": "approver",
"delegated_from": "text",
"reassigned_from": "text",
"status": "text",
"claimed_at": "2026-01-01T00:00:00.000Z",
"completed_at": "2026-01-01T00:00:00.000Z",
"due_at": "2026-01-01T00:00:00.000Z",
"decision_id": "text",
"decision_action": "text",
"decision_comment": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"context": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"artifact_type": "text",
"artifact_id": "text",
"policy_key": "text",
"search_text": "text"
}approveSuccessful Response
Bearer token missing, malformed, or fails signature/expiry checks.
Task is not assigned to the caller and the caller is not an admin.
No approval request with the given id.
Resource is in a state that disallows this transition. Examples: request is already in a terminal state (approved/rejected/cancelled); task is not open/claimed; policy version is not draft for editing; delivery has already succeeded.
Validation Error
POST /v1/awe/tasks/{task_id}/decision HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 62
{
"action": "approve",
"comment": "text",
"attachments_ref": "text"
}{
"id": "text",
"request_id": "text",
"task_id": "text",
"stage_order": 1,
"actor": "text",
"action": "text",
"comment": "text",
"attachments_ref": "text",
"created_at": "2026-01-01T00:00:00.000Z"
}Webhook (outbound from AWE → Caller)
AWE POSTs to whatever callback_url was set on the request whenever a status-changing event occurs. The contract — body schema and the three signed headers — is declared in the OpenAPI spec under the top-level webhooks: field (OpenAPI 3.1 feature) so it's discoverable from the same artifact as the rest of the API.
Sent by AWE to the caller's callback_url whenever a status-changing event occurs on an approval request — request_created, stage_started, stage_completed, request_approved, request_rejected, request_cancelled, or task_expired.
Signature scheme: X-Approval-Signature is sha256= + HMAC-SHA256 over <X-Approval-Timestamp>.<raw body> using the per-caller shared secret. The caller must verify the signature, dedup on X-Approval-Event-Id, and return any 2xx within the configured timeout (default 10s). Non-2xx triggers retries on the schedule documented in functional-specifications (1m → 5m → 15m → 1h → 6h, ~27h total).
The body POSTed to the caller's callback_url.
Headers (set by the dispatcher, not part of this body):
X-Approval-Event-Id — same as event_id below
X-Approval-Signature — sha256=<hex>, HMAC over the raw body
X-Approval-Timestamp — Unix seconds, included in the signed payload
7f3e...request_created | stage_started | stage_completed | request_approved | request_rejected | request_cancelled
request_approvedSuccessful Response
Validation Error
Payload
{
"event_id": "7f3e...",
"event_type": "request_approved",
"request_id": "text",
"artifact_type": "text",
"artifact_id": "text",
"status": "text",
"stage_order": 1,
"actor": "text",
"occurred_at": "2026-01-01T00:00:00.000Z"
}Last updated
Was this helpful?