Skip to main content

Approvals & Webhooks

When a policy resolves to approval_required, OpenProdkt does not execute the request and returns a governed approval decision. SDK integrations may wait or poll for resolution; proxy mode never waits for approval and blocks the original request immediately.

SDK and proxy modes​

ModeWhile approval is pendingAfter approval
SDKThe SDK may wait for a bounded time, or return approval_id for app-managed polling or webhook handling.Your app retries with the same operation_id, approval_id, and payload_hash.
ProxyThe proxy immediately returns HTTP 403 or gRPC PERMISSION_DENIED; the protected upstream is not called. A CX/orchestrator polls or receives the approval webhook.The app retries the original request with the same stable operation_id; the client does not need to send approval_id.

Proxy mode is transparent to business logic. If the request contains a stable operation_id, OpenProdkt can automatically correlate the retry and consume the approval in a single successful redemption. This is an approval state transition only. approval_id is optional for the proxy client. Identical metadata alone cannot distinguish a retry from a separate operation.

A single redemption does not guarantee exactly-once execution by your upstream. If the authorization response is lost after redemption, OpenProdkt will not redeem that approval again, and the upstream outcome may be unknown. Make the business operation idempotent using the same operation_id and reconcile ambiguous outcomes in your application.

Numeric metadata uses exact decimal canonicalization: 100, 100.0, and 1e2 have the same metadata binding. MCP's separate complete-arguments digest still preserves numeric text. An update that changes numeric approval canonicalization requires a coordinated approval drain on both upgrade and rollback; do not rewrite stored hashes or bypass a retry mismatch. Invalid context blocks a retry before approval redemption, without consuming the approval.

Proxy challenge​

When a proxied request needs approval, /v1/proxy/evaluate returns HTTP 403 immediately, with Retry-After: 30 and Cache-Control: no-store. The protected upstream is not called. gRPC callers receive PERMISSION_DENIED. The body contains:

FieldValue
codeapproval_required
retry_after_seconds30 (seconds; fixed, not configurable)
grant_ttl_seconds120 (seconds; how long an approved operation can be redeemed)
status_url/v1/proxy/operations/{operation_id}, where the operation can be polled
operation_idEchoed when it matches ^[A-Za-z0-9._:-]{1,128}$; omitted otherwise
approval_expires_atWhen the pending approval expires
{
"code": "approval_required",
"retry_after_seconds": 30,
"grant_ttl_seconds": 120,
"status_url": "/v1/proxy/operations/refund-2026-001",
"operation_id": "refund-2026-001",
"approval_expires_at": "2026-09-13T11:15:00Z"
}

status_url and operation_id are present only when the operation ID matches the pattern above. The challenge never includes the approval ID or the payload hash. The CX or orchestrator tracks the approval through polling or webhooks. The application retries the original request with the same operation_id after approval.

How it works​

The SDK flow does not silently replay your business request. Your application owns the retry unless it opts into a bounded SDK wait.

For details on plans and how licensing works, see Licensing & Distribution.

Choose a delivery model​

OptionHow it worksBest for
Async + Webhook (recommended)SDK apps or the CX/orchestrator receive an approvalId; OpenProdkt sends lifecycle events to a registered webhook endpointBackend jobs, agents
App-managed retry (SDK)Your app stores approvalId, a human approves in the Console, your app retries the original operation with the explicit tupleWeb/mobile apps
Short wait (SDK)The SDK blocks for a bounded time polling for resolution, then returns the result or a timeoutInteractive apps
Polling (SDK/CX)The SDK app or CX/orchestrator checks status via GET /v1/approvals/{id}Integrations without webhooks
Transparent proxyThe proxy immediately blocks pending requests; after approval, the app retries the original request with the same stable operation_idExisting applications behind the proxy

SDK integrations may wait or poll. Proxy integrations never wait for approval: they block immediately and rely on the CX/orchestrator to observe resolution before the request is retried.

Async + Webhook​

For SDK flows, your application receives the approval ID in the challenge. For proxy flows, the CX/orchestrator owns the approval handle; the protected application does not need it. Register a webhook endpoint from the Console (Settings → Webhooks) or via POST /v1/webhooks, with a URL and the event types you want: approval.pending, approval.approved, approval.rejected, approval.expired, approval.revoked. Each delivery includes a stable eventId in the body and X-OpenProdkt-Event-Id header, plus an X-OpenProdkt-Timestamp header. Verify X-OpenProdkt-Signature using the endpoint secret shown once at creation. During secret rotation, configure the receiver to accept both the previous and new secret until in-flight deliveries have drained. The versioned format is v1=sha256=<hex HMAC-SHA256> over the timestamp, an ASCII period, and the exact raw request body. Enforce a replay window on the timestamp and durably deduplicate on event ID before handling the event. The bundled SDKs accept timestamps within 5 minutes (Go) or 300 seconds (Python and TypeScript).

App-managed retry​

This explicit mode is for SDK integrations whose application manages the approval workflow. Store the operation_id, approvalId, payload_hash, and the exact asset identity and authorization context returned by the initial approval_required decision. When a reviewer resolves it in the Console (or your webhook fires), retry /v1/evaluate with the same operation_id, asset, transport, and metadata, plus the original approval_id and payload_hash:

{
"version": "v1",
"asset": { "id": "ast_e8f1a2c3" },
"operation_id": "refund-2026-001",
"approval_id": "apr_5c6d7e8f",
"payload_hash": "sha256:<hash returned by the initial decision>",
"transport": { "kind": "http" },
"metadata": { "operation": "refund", "amount": 9000 }
}

OpenProdkt recomputes the canonical payload hash and checks the organization, authenticated principal, operation, asset, transport, metadata, and policy revision binding. A changed context is rejected rather than treated as a new authorization. A pending approval remains pending; the first valid approved retry atomically redeems it and returns allow. Later attempts report the consumed status and do not authorize again. Rejected, expired, revoked, unknown, or mismatched approvals do not authorize the operation. The application must still make the business operation idempotent using the same operation_id to handle an ambiguous upstream result.

Transparent proxy retry​

Proxy mode is transparent to business logic. If the request contains a stable operation_id, OpenProdkt can automatically correlate the retry and consume the approval in a single successful redemption. This is an approval state transition only, not upstream execution. approval_id is optional for the proxy client. The CX/orchestrator polls the approval or receives its webhook; the protected application does not wait and does not need to know the approval ID. After approval, it resends the original request through the proxy with the same operation_id and authorization context. The proxy immediately blocks while approval is pending and never holds the original request open.

A single redemption is not exactly-once upstream execution. If the authorization response is lost after redemption, the approval cannot be redeemed again and the upstream outcome may be unknown. Make the business operation idempotent with the same operation_id and reconcile ambiguous outcomes. Without a stable operation_id, a matching request fingerprint alone is not enough to redeem an approval.

Short wait (SDK)​

SDKs expose an opt-in bounded wait — see SDK Manual — that polls internally and returns either the resolved decision or a timeout. This never replaces async delivery; it's for interactive UX where a user is actively waiting.

Polling (SDK/CX)​

GET /v1/approvals/{id} returns the current status of a single approval. SDKs expose get_approval_status() (Python), GetApprovalStatus() (Go), and getApprovalStatus() (TypeScript) for this scoped lookup; polling reads one approval and does not list or reevaluate requests. API keys must include the approvals:read scope. A decision-only key receives a 403 with code=insufficient_scope; the SDK reports this as a typed scope error rather than a PDP outage. Async delivery remains the recommended default.

An authorized reviewer (a user JWT with the super_admin or user role) may revoke a pending or approved approval with POST /v1/approvals/{id}/revoke. Revocation records revokedAt, clears any unconsumed grant, and emits approval.revoked; later explicit retries remain denied.

Review in the Console​

Approvers review requests under Approvals in the Console. Each request shows its asset, requester ID, operation, policy, status, creation and expiry times, and, once resolved, the reviewer and comment. For an MCP tool call, the request also shows the MCP server and tool name. From a request you can:

  • Approve or reject, with an optional comment. Only super admins and the owner of the asset can act on it.
  • Open View decision to see the policy evaluation for the request.
  • Open View audit history to see the audit events recorded for it.

Each request also shows Oversight indicators: how long review took, how long a pending request has been waiting, whether the reviewer differs from the requester, whether a review comment is present, and whether it expired without review. These are factual values from stored approval data when you load the page. They are not a quality score, a risk rating or sealed evidence, and a value that is not stored is simply not shown. The API returns the same values in an additive oversight object on GET /v1/approvals and GET /v1/approvals/{id}; the comment text is never part of it.

The decision and its audit event are recorded together, so a resolved request always has an audit entry.

Email notifications​

When a request requires approval, OpenProdkt sends an email to the approvers listed on the asset's group and to the organization's super admins and owners. Each address receives one email. If the asset has no group, only the super admins and owners receive it.

A group approver who is not a super admin or organization owner, and who does not own the asset, receives the email but cannot approve or reject the request in the Console. Approving by group membership is not yet available.

The email summarizes the request: the asset, the requester ID, the operation, the policy, the expiry time, the organization, the approval ID, and the decision ID. For an MCP tool call, it also names the MCP server and tool. When the Console address is configured, it also includes a link that opens the request in the Console.

  • The email does not approve or reject the request. Recipients sign in to the Console with the one-time email code and act there.
  • The link points to the request in the Console. Users see only the requests their role allows them to review. If you are signed out, sign in first, then open Approvals to find the request.
  • Operators set the Console address on the worker with OPK_CONSOLE_BASE_URL, for example https://console.example.com. It must be an absolute http or https URL without a query string or fragment. When it is not set, the email has no link and asks the recipient to open Approvals in the Console.

Redemption, expiry, and retry rules​

ItemValueConfigurable
Pending approval lifetime24 hours from creationNo
Grant window after approval2 minutes (grant_ttl_seconds = 120)No
Effective redemption deadlineThe earlier of the grant window end and the approval expiryNo
Proxy retry hintRetry-After: 30 secondsNo
In-flight claim on an operation5 minutes, after which another request with the same operation ID can take overNo

Redemption is atomic: one approved approval can be consumed once. A retry is accepted only if it matches the original request on organization, principal, operation_id, asset identity, and the payload hash. The payload hash is a sha256: digest over a canonical form of the policy revisions in force, the transport context (MCP request and session IDs excluded), and the metadata. If the policies, the asset schema, or the metadata change after the approval was created, the retry returns 409 approval_retry_mismatch; start a new operation.

Only published, active policies participate in these bindings. Publishing a new revision or archiving a live policy changes the policy set and invalidates stale retries. Editing an unrelated draft does not change the live policy set. Adding lifecycle status alone does not change existing approval-hash encoding. Validation and simulation never redeem or create an approval; a simulated approval_required result is only a preview.

Retry outcomes use these reasons. Only approval_granted allows the call.

ReasonDecision
approval_pendingapproval_required
approval_grantedallow (the approval is consumed)
approval_consumed, approval_rejected, approval_expired, approval_grant_expired, approval_revoked, approval_not_redeemabledeny

Approve, reject, and revoke need a user session with an authorized role; API keys receive jwt_user_required. An approver cannot be the requester (self_approval_forbidden). Expiry is applied when approvals or operations are next read, so the approval.expired event can be emitted later than the expiry time.

An approved operation records its decision, not its execution. Report the real result through the operation outcome endpoint so the audit trail shows whether the upstream call ran. The first outcome reported wins; a different later report returns 409 operation_outcome_conflict. See Audit.

Webhook delivery and retries​

Webhook delivery is asynchronous and at-least-once.

  • Dispatch is off unless the operator sets OPK_OUTBOX_DISPATCH_ENABLED. Without it, no webhooks, approval emails, or approval lifecycle records are produced.
  • Each delivery has a 10-second connect timeout and a 10-second overall timeout. Redirects are not followed and no proxy is used. A non-2xx response or a network error counts as a failure.
  • Failed events are retried with exponential backoff starting at 1 minute and capped at 1 hour, plus jitter, up to 5 attempts by default. After the last attempt the event is dead-lettered and is not retried again. The operator can change the attempt count and batch size; see Limits and Configuration.
  • If several endpoints subscribe to the same event, one failing endpoint can cause redelivery to the others. Receivers must deduplicate on eventId.
  • Each request carries X-OpenProdkt-Event-Id, X-OpenProdkt-Timestamp, and X-OpenProdkt-Signature (v1=sha256=<hex>, an HMAC-SHA256 of timestamp + "." + body with the endpoint secret). Reject timestamps older than your replay window; the SDK helpers use 5 minutes.
  • The body is { eventId, eventType, organizationId, aggregateId, data }.
  • Destinations are checked after DNS resolution on every attempt. Loopback, private, link-local, and reserved ranges are refused by default, cloud metadata addresses are always refused, and https can be required by the deployment. Self-hosted operators can opt specific ranges in with OPK_WEBHOOK_ALLOWED_CIDRS.

Approval scope​

An approval is never a permanent permission — it's scoped to a single request:

  • Asset — what the request was about
  • Policy — which rule triggered the review
  • Request/context — the metadata submitted with the decision
  • Requester — who or what made the call
  • Expiration — pending approvals expire 24 hours after creation and move to expired. An approved approval is redeemable within a 2-minute grant window (grant_expires_at); a redemption after that window is refused
  • Status — pending, approved, rejected, expired, revoked, or consumed after one successful redemption
{
"id": "apr_5c6d7e8f",
"decisionId": "dec_9f2a1c4e",
"assetId": "invoice-agent",
"policyId": "pol_8a1b2c3d",
"requesterId": "key_4f5e6d7c",
"status": "pending",
"expiresAt": "2026-09-13T11:15:00Z"
}

See API Reference for the full approvals and webhooks endpoint list, and SDK Manual for language-specific helpers.