DEVELOPERS

Webhooks

Enterprise event notifications for PayReality: the planned shape, not a live subscription API yet.

PLANNEDToday, decisions are retrieved by polling GET /v1/decisions/{id} (see Runtime API).

Rather than requiring every integration to poll for state changes, the planned webhook system notifies your enterprise system directly when something happens inside PayReality. The seven events below are the planned taxonomy: two of them, PolicyPublished and AuthorityGraphUpdated, are distinct from the rest because they signal that governance itself changed, which changes what every subsequent decision is evaluated against, not just that one more decision was made. ExecutionReconciled is distinct for a different reason: it doesn't fire when PayReality decides anything, it fires when a separately authenticated destination reports back what actually happened, and that report is reconciled against the decision. See Runtime API for the reconciliation outcome values it carries.

Event taxonomy

IntentReceived

An Intent was received and passed signature verification, before evaluation.

DecisionCompleted

Evaluation finished with an Allow or Deny outcome.

HumanReviewRequested

Evaluation resolved to Human Review and is now pending.

ReceiptIssued

A signed evidence record (planned: an Authorization Receipt) was issued for a decision.

PolicyPublished

A Runtime Policy moved to active and is now being evaluated against Intents.

AuthorityGraphUpdated

A new version of the Authority Graph was published.

ExecutionReconciled

A trusted destination or execution adapter's execution receipt was reconciled against a decision (MATCHED, MISMATCHED, EXECUTION_FAILED, PARTIAL, RECEIPT_MISSING, or INDETERMINATE).

Planned payload shape

DecisionCompleted (planned shape)

{
  "event": "DecisionCompleted",
  "event_id": "evt_4c91a2",
  "occurred_at": "2026-08-03T09:14:02.118Z",
  "data": {
    "decision_id": "dec_3a91f0",
    "outcome": "ALLOW",
    "agent_id": "agt_8f2b1c",
    "evidence_id": "ev_7c02d4"
  }
}

HumanReviewRequested (planned shape)

{
  "event": "HumanReviewRequested",
  "event_id": "evt_4c91a3",
  "occurred_at": "2026-08-03T09:14:02.077Z",
  "data": {
    "decision_id": "dec_3a91f2",
    "agent_id": "agt_8f2b1c",
    "reason": "requires_dual_approval"
  }
}

ExecutionReconciled (planned shape)

{
  "event": "ExecutionReconciled",
  "event_id": "evt_4c91a4",
  "occurred_at": "2026-08-03T09:16:41.203Z",
  "data": {
    "decision_id": "dec_3a91f0",
    "reconciliation_status": "MATCHED",
    "receipt_id": "exec_rcpt_9a1f..."
  }
}

A cryptographically authenticated execution receipt proves what the trusted source reported. It does not independently prove that the underlying business system or real-world event was truthful.

Why polling works today regardless

Nothing about the current Runtime API depends on webhooks existing: ALLOW and DENY are terminal in the same response you already receive, and Human Review can be tracked by polling the decision until its status resolves. Webhooks remove the need to poll; they don't unlock a capability that's otherwise unavailable.

Other documentation

Getting StartedCreate an organization, register an agent, and get your first Authorization Receipt back.ArchitectureThe full path from an agent's signed intent to a decision and its evidence, component by component.Runtime APIThe Intent API: POST /v1/intents, its three possible outcomes, and the request/response lifecycle.AuthenticationThe Operator Key, per-user roles and permissions, per-developer API keys, and agent certificates.Authority GraphDelegated authority, roles, resources, and approval limits, and how governance becomes machine-readable.Runtime PoliciesHow a policy is compiled, versioned, and deployed, and why that differs from the governance document it came from.Authorization ReceiptsWhy logs aren't enough, the receipt lifecycle, and the planned architecture for independent verification.Evidence VerificationSignature verification, evidence export, and audit workflows against the Evidence Portal today.SDKsThe Python SDK, and the language roadmap for Node.js, Go, Java, .NET, and Rust.Integration ExamplesRotating keys, sending a heartbeat, and retiring an agent, with real SDK code for each.Integration GuidesConnecting Runtime Authority to agent frameworks, model providers, and enterprise systems.Agent RegistrationThe full agent lifecycle: registered, active, suspended, retired, or revoked.API ReferenceEndpoints, schemas, headers, status codes, errors, and versioning.Order WalkthroughOne order, followed end to end: signed intent, declared material fields, capability issuance, rejection on a changed field, and what the receipt path does and doesn't prove.