> For the complete documentation index, see [llms.txt](https://docs.sectoral.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sectoral.xyz/ai-agents/event-stream.md).

# Real-Time Event Stream

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 Sectoral with an HMAC, using a secret that is displayed only once when you create the subscription

On each request, verify the `X-Sectoral-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

```json
{
  "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 Sectoral'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.

***

## Read next

* [Wallets for Agents](/ai-agents/agent-wallets.md)
* [Webhook Endpoints](/developer-api/webhooks.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sectoral.xyz/ai-agents/event-stream.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.