Webhooks

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

Planned payload 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"
  }
}

{
  "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"
  }
}

{
  "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.