DocsSign inGet your account
Get your account
AI agents

Real-Time Event Stream

Beta. Parts of what these docs describe are still being built. The roadmap shows what is live today.

Each payment involving your account, or any agent under it, is delivered to you in real time. That keeps dashboards, parent apps and monitoring tools up to date the instant funds move, with no polling and no lag.

Setting up a subscription

Use Dashboard → Developer → Webhooks, or do it through the API:

  1. Provide an HTTPS endpoint that accepts POST requests
  2. Pick the event types you want delivered to it
  3. Every payload is signed by Cyphron with an HMAC, using a secret that is displayed only once when you create the subscription

On each request, verify the X-Cyphron-Signature header against that secret before acting on the body.

Event types

Event Fires when
transfer.initiated A payment was submitted and is waiting to be confirmed
transfer.confirmed A payment reached on-chain settlement
transfer.failed A payment failed to settle
agent.transaction.pending_approval An agent's payment went over its approval threshold
agent.transaction.approved A person approved an agent payment that was on hold
agent.transaction.rejected A person declined an agent payment that was on hold
agent.policy.updated One of your agents had its spend policy modified

Example payload

{
  "event": "transfer.confirmed",
  "account": "@yourname/research-bot",
  "direction": "sent",
  "counterparty": "api.market",
  "asset": "USDG",
  "confidential": true,
  "tx_hash": "0x8f3ad41c9be2...7c1a",
  "timestamp": "2026-07-02T14:23:09Z"
}

You'll notice there is no amount. That is deliberate. Confidential transfers store encrypted values on-chain, and Cyphron's backend never holds your decryption key, so it has no number to send. If your integration needs the amount, decrypt it on the client with your own key, which is exactly how the app displays your feed.

Failed deliveries

If a delivery gets anything other than a 2xx response, we retry it with exponential backoff for as long as 24 hours. You can also resend missed events manually from the webhook log in the dashboard, so a brief outage won't leave a gap in your records.