> ## Documentation Index
> Fetch the complete documentation index at: https://docs.teel.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> Receive real-time updates for transaction and account status changes

Teel sends real-time updates whenever events occur on your account (payout created, status changed, etc.). There are two delivery modes — pick whichever fits your stack:

* **HTTP webhooks** — Teel POSTs HMAC-signed events to a URL you register. See [Subscriptions](/api-reference/webhooks/subscriptions) and [Deliveries](/api-reference/webhooks/deliveries) for the management endpoints, and the [Webhooks guide](/guides/webhooks) for the verifier samples + retry rules.
* **WebSocket** — Connect to `wss://api.teel.finance/ws` and authenticate in-band with your API key. See the [Webhooks guide](/guides/webhooks#websocket-connection) for the client snippet.

Both deliver the same events with the same payload shape.

## Event types

Teel publishes a unified event stream covering payout lifecycle, recipient changes, and account-level updates. The most common events:

| Event                   | When it fires                                   |
| ----------------------- | ----------------------------------------------- |
| `payout.status.updated` | Payout step or status changed                   |
| `payout.delivered`      | Payout reached the recipient (terminal success) |
| `payout.failed`         | Payout failed (terminal)                        |
| `recipient.created`     | New recipient added to your account             |
| `recipient.updated`     | Existing recipient changed                      |

See the [Webhooks guide](/guides/webhooks) for the full event catalogue and payload shapes.

## Responding to webhooks

Return a `2xx` response within 10 seconds to acknowledge receipt. Non-2xx responses (or timeouts) trigger automatic retries with exponential backoff. Make your handler idempotent — Teel may deliver the same event more than once during partial outages.