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

# Overview

> Push notifications for blockchain events

Webhooks deliver real-time POST notifications to your server when blockchain events occur.
The SDK provides a low-level client for webhook CRUD and a high-level dispatcher with
decorator-based event handling.

<Info>
  API key is **required** for all webhook operations. Get one at [tonconsole.com](https://tonconsole.com/).
</Info>

## Architecture

| Component                 | Description                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| `TonapiWebhookClient`     | HTTP client for webhook CRUD — create, list, delete, subscribe/unsubscribe.                |
| `TonapiWebhook`           | Bound webhook object — manages subscriptions without explicit ID.                          |
| `TonapiWebhookDispatcher` | Decorator-based event dispatcher — register handlers, auto-setup, process incoming events. |

## Event Types

| Type          | Enum            | Decorator                     | Description                  |
| ------------- | --------------- | ----------------------------- | ---------------------------- |
| Account TX    | `ACCOUNT_TX`    | `@dispatcher.account_tx()`    | Account transactions.        |
| Mempool MSG   | `MEMPOOL_MSG`   | `@dispatcher.mempool_msg()`   | Pending mempool messages.    |
| Opcode MSG    | `OPCODE_MSG`    | `@dispatcher.opcode_msg()`    | Messages filtered by opcode. |
| New Contracts | `NEW_CONTRACTS` | `@dispatcher.new_contracts()` | New contract deployments.    |

## Endpoints

| Network | URL                            |
| ------- | ------------------------------ |
| Mainnet | `https://rt.tonapi.io`         |
| Testnet | `https://rt-testnet.tonapi.io` |

## Quick Example

FastAPI integration with automatic webhook setup and event dispatch:

```python theme={"theme":{"light":"github-light-default","dark":"dark-plus"}}
from contextlib import asynccontextmanager

import uvicorn
from fastapi import FastAPI, Request, Response

from pytonapi.types import Network
from pytonapi.webhook import (
    AccountTxEvent,
    TonapiWebhookClient,
    TonapiWebhookDispatcher,
)

client = TonapiWebhookClient("YOUR_API_KEY", Network.MAINNET)
dispatcher = TonapiWebhookDispatcher(
    "https://example.com/webhook",
    client=client,
    accounts=["EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2"],
)


@dispatcher.account_tx()
async def on_tx(event: AccountTxEvent) -> None:
    print(f"TX: {event.tx_hash}")


async def handle_webhook(request: Request) -> Response:
    await dispatcher.process(
        request.url.path,
        await request.json(),
        authorization=request.headers.get("Authorization"),
    )
    return Response(status_code=200)


@asynccontextmanager
async def lifespan(application: FastAPI):
    await dispatcher.setup()
    for path in dispatcher.paths.values():
        application.add_api_route(path, handle_webhook, methods=["POST"])
    yield
    await dispatcher.teardown()


app = FastAPI(lifespan=lifespan)

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

See [Guide](/webhooks/guide) for the full client API, dispatcher options, and aiohttp integration.

<Note>
  Each webhook has a unique secret token. TON API sends it as `Authorization: Bearer {token}` with every event delivery — use it to verify that incoming requests are genuine. The dispatcher verifies it automatically in `process()`.
</Note>

## Event Models

All models are Pydantic `BaseModel` subclasses.

```python theme={"theme":{"light":"github-light-default","dark":"dark-plus"}}
from pytonapi.webhook import AccountTxEvent, MempoolMsgEvent, OpcodeMsgEvent, NewContractsEvent
```

<Accordion title="AccountTxEvent">
  | Field        | Type                    | Description            |
  | ------------ | ----------------------- | ---------------------- |
  | `event_type` | `Literal["account_tx"]` | Always `"account_tx"`. |
  | `account_id` | `str`                   | Account address.       |
  | `lt`         | `int`                   | Logical time.          |
  | `tx_hash`    | `str`                   | Transaction hash.      |

  ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"}}
  {
    "event_type": "account_tx",
    "account_id": "0:408da3b28b6c065a593e10391269baaa9c5f8caebc0c69d9f0aabbab2a99256b",
    "lt": 49739623000001,
    "tx_hash": "653e593d581ad40d5d0868fe5d60008e1bfe9d2d4c4fa6b2ee5cd458741d7b59"
  }
  ```
</Accordion>

<Accordion title="MempoolMsgEvent">
  | Field        | Type                     | Description             |
  | ------------ | ------------------------ | ----------------------- |
  | `event_type` | `Literal["mempool_msg"]` | Always `"mempool_msg"`. |
  | `boc`        | `str`                    | Base64-encoded BOC.     |

  ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"}}
  {
    "event_type": "mempool_msg",
    "boc": "te6cckEBAQEADgAAGEhlbGxvIFRPTiEN"
  }
  ```
</Accordion>

<Accordion title="OpcodeMsgEvent">
  | Field        | Type                    | Description            |
  | ------------ | ----------------------- | ---------------------- |
  | `event_type` | `Literal["opcode_msg"]` | Always `"opcode_msg"`. |
  | `account_id` | `str`                   | Account address.       |
  | `lt`         | `int`                   | Logical time.          |
  | `tx_hash`    | `str`                   | Transaction hash.      |

  ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"}}
  {
    "event_type": "opcode_msg",
    "account_id": "0:408da3b28b6c065a593e10391269baaa9c5f8caebc0c69d9f0aabbab2a99256b",
    "lt": 49739623000001,
    "tx_hash": "653e593d581ad40d5d0868fe5d60008e1bfe9d2d4c4fa6b2ee5cd458741d7b59"
  }
  ```
</Accordion>

<Accordion title="NewContractsEvent">
  | Field        | Type                       | Description               |
  | ------------ | -------------------------- | ------------------------- |
  | `event_type` | `Literal["new_contracts"]` | Always `"new_contracts"`. |
  | `account_id` | `str`                      | Account address.          |
  | `lt`         | `int`                      | Logical time.             |
  | `tx_hash`    | `str`                      | Transaction hash.         |

  ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"}}
  {
    "event_type": "new_contracts",
    "account_id": "0:408da3b28b6c065a593e10391269baaa9c5f8caebc0c69d9f0aabbab2a99256b",
    "lt": 49739623000001,
    "tx_hash": "653e593d581ad40d5d0868fe5d60008e1bfe9d2d4c4fa6b2ee5cd458741d7b59"
  }
  ```
</Accordion>

<Note>
  All webhook events are finalized — there is no pending/confirmed distinction unlike streaming mempool events.
</Note>