> This page is for version v5.0.
> For other versions, use one of these documentation indexes:
> - v6.0 (default): https://docs.zip.tax/v-6-0/llms.txt
> - v5.0: https://docs.zip.tax/v-5-0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.zip.tax/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.zip.tax/_mcp/server.

# Event Webhooks Overview

Event Webhooks let your account receive real-time HTTP notifications when
something changes in Ziptax, instead of polling the API. When a subscribed
event occurs, Ziptax sends an HTTP `POST` request with a JSON body to each
endpoint URL your account has configured.

> **Warning**
>
> The webhook body is only a notification that something changed. It does not
> carry the changes themselves. For `rate.updated`, the payload tells you which
> tax authority changed (and, at [Postal code granularity](configure#granularity-level)
> on Enterprise plans, which postal codes were affected). When you receive it,
> call the [Ziptax rate API](../rest-api/overview) to fetch the updated rates for
> that authority.

## How it works

### You configure one or more endpoints

Add the HTTPS URLs that should receive notifications from your account's `Develop > Events` page.

### A subscribed event occurs

For example, sales tax rates change for a tax authority you care about.

### Ziptax delivers the event

Ziptax sends an HTTP `POST` with a JSON body to **every** configured endpoint.

### Your endpoint acknowledges, then acts

Respond quickly with a `2xx` status, then fetch the authoritative data from the Ziptax API.

## When to use webhooks

Use Event Webhooks when you want to react to changes as they happen without
running a polling loop against the API. The current use case is keeping your
own cached rates fresh: subscribe to `rate.updated` and re-fetch rates for an
authority only when it actually changes.

## Explore the docs

#### [Prerequisites & access](prerequisites)

Plan requirements, roles, and where to find the feature.

#### [Configure an endpoint](configure)

Add endpoint URLs and choose which events to subscribe to.

#### [Events reference](events)

The event catalog and payload schema.

#### [Verify & secure deliveries](verify)

The signing secret and how to keep endpoints secure.

#### [Test & monitor](testing)

Send test events and check delivery status.

#### [Best practices](best-practices)

Patterns for reliable, secure webhook handling.