Webhooks Overview - Teel API

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 and Deliveries for the management endpoints, and the Webhooks guide 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 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 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.