# Webhooks overview

Webhooks allow your apps to receive information when events matching your Trigger conditions occur, and respond however you define.

Webhooks deliver data to your apps as they happen; you get the data you want immediately instead of having to poll (look) for changes to data. For example, we can send your app a notification when the balance of any of the wallets you're watching changes.

We don't currently support webhook request authentication via headers, but it's on our roadmap. 

You should **always verify** that webhook requests originate from the `api.dispatch.esprezzo.io` domain; any other origin is not a legitimate Dispatch webhook request.

{% hint style="danger" %}
**Important**

You should always verify that webhook requests originate from the <mark style="color:purple;">`api.dispatch.esprezzo`</mark> domain.

Any other origin is **not** a legitimate Dispatch webhook request and could pose a security risk.
{% endhint %}

### Event types

Webhooks can be triggered by several types of events (Triggers) in Dispatch:

* **Address activity**: wallet balance of a specific token changed, or went above or below a threshold
* **Smart contract activity**: anytime selected events are emitted by, or functions are called in smart contracts
  * Lots of possibilities:&#x20;
    * Alerts for unexpected AdminChange, Pause, Unpause events that could indicate security vulnerabilities
    * Mint, transfer, upgrade & gameplay events on ERC721, ERC1155, ERC1967, ERC-4337
    * Swap, trade & new pair/pool events on DEX contracts
    * Any verified contract on Ethereum, Polygon, Base & Avalanche, with more networks coming soon

### Webhook format

Every Dispatch webhook uses the same format, regardless of event type. The webhook request is a standard HTTP POST, and the request body will contain a JSON payload with the following top-level keys:

* <mark style="color:purple;">`patch`</mark>: information about the associated Patch (e.g. <mark style="color:purple;">`patch.id`</mark>, <mark style="color:purple;">`patch.name`</mark>, etc). This object also contains information about the Trigger as well (e.g. <mark style="color:purple;">`trigger.template_id`</mark>, <mark style="color:purple;">`trigger.settings`</mark>, etc).
* <mark style="color:purple;">`details`</mark>: information about the actual event that has occurred (e.g. <mark style="color:purple;">`details.token_symbol`</mark>, <mark style="color:purple;">`details.new_balance`</mark>, etc for "address balance change" Triggers).

The <mark style="color:purple;">`details`</mark> object will contain different data based on the Trigger type. See the [Webhook Reference](/webhooks/webhook-reference.md) for more details.

### What you'll need

1. **Dispatch account** ([log in](https://dispatch.esprezzo.io/login) or [sign up](https://dispatch.esprezzo.io/signup))
2. **A webhook URL**: an endpoint on your server that receives requests from Dispatch alerting you about events that happen

{% hint style="warning" %}
**Important:** Make sure your endpoint is publicly accessible so we can send unauthenticated POST requests.
{% endhint %}

### Example: Sending smart contract or wallet activity to Google Sheets&#x20;

With webhooks, you can use Dispatch with Zapier to send on-chain data to apps in the Zapier ecosystem, or use on-chain activity to automate tasks in apps you and your team already use.

Check out this guide to see an example: [Automatically log on-chain activity to Google Sheets without code](https://blog.esprezzo.io/automatically-log-on-chain-activity-to-google-sheets-without-any-code)


---

# Agent Instructions: 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:

```
GET https://docs.esprezzo.io/webhooks/webhooks-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.