> 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. # Events reference Every webhook delivery is an HTTP `POST` with a JSON body. This page documents the events you can subscribe to and the shape of what Ziptax sends. ## Event catalog | Event | Description | | -------------- | ---------------------------------------------------------------- | | `rate.updated` | Sent when sales tax rates change for the provided tax authority. | > **Info** > > `rate.updated` is the only event available today. More event types are coming > soon. ## Payload schema All events share the same top-level shape: `event`, `timestamp`, and `data`. ### Example: `rate.updated` ```json { "event": "rate.updated", "timestamp": "2026-06-11 00:00:00.000Z", "data": { "rateUpdateDetail": { "locality": "USA-STATE", "code": "CA" } } } ``` ### Notification granularity Your account's [Granularity Level](configure#granularity-level) controls how much location detail each `rate.updated` notification carries: * **State/Province** (the default): the payload identifies the tax authority that changed — `locality` and `code` — as shown above. * **Postal code** (Enterprise plans only): the payload additionally includes `postalcodeList`, the postal codes affected by the change. #### Example: `rate.updated` at Postal code granularity ```json { "event": "rate.updated", "timestamp": "2026-06-11 00:00:00.000Z", "data": { "rateUpdateDetail": { "locality": "USA-STATE", "code": "CA", "postalcodeList": ["92101", "92103", "92130"] } } } ``` > **Info** > > Treat `postalcodeList` as optional in your parser: it never appears at > State/Province granularity, and a notification may omit it when postal-code > detail is not available for a given change. Everything else in the payload is identical > across granularity levels. ### Field reference | Field | Type | Description | | -------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `event` | string | The event type, e.g. `rate.updated`. | | `timestamp` | string | When the event was generated (UTC). | | `data` | object | Event-specific payload. | | `data.rateUpdateDetail.locality` | string | The kind of tax authority that changed. One of `USA-STATE` or `CAN-PROVINCE`. See [Tax authority values](#tax-authority-values). | | `data.rateUpdateDetail.code` | string | The two-letter code of the state, province, or territory within that locality (example value: `CA`). See [Tax authority values](#tax-authority-values). | | `data.rateUpdateDetail.postalcodeList` | array of strings | The postal codes affected by the change. Included only when your account's [Granularity Level](configure#granularity-level) is **Postal code** (Enterprise plans only). See [Notification granularity](#notification-granularity). | > **Warning** > > `locality`, `code`, and `postalcodeList` identify **where** rates changed. To > get the new rate values, call the [Ziptax rate API](../rest-api/overview) for > those locations. The webhook body is a trigger, not the rate data itself. ## Tax authority values `locality` is always one of two values, and `code` is the two-letter code of the state, province, or territory within that locality: | Locality | Meaning | | -------------- | ------------------------------------------------------------ | | `USA-STATE` | A U.S. state, the District of Columbia, or a U.S. territory. | | `CAN-PROVINCE` | A Canadian province or territory. | The complete set of `locality` and `code` combinations Ziptax can send is listed below. Expand the table to browse it, or use the button to copy the full table as CSV without expanding. Copy table as CSV
Show all tax authority values (69) | Locality | Code | Description | | -------------- | ---- | ------------------------- | | `USA-STATE` | `AL` | Alabama | | `USA-STATE` | `AK` | Alaska | | `USA-STATE` | `AZ` | Arizona | | `USA-STATE` | `AR` | Arkansas | | `USA-STATE` | `CA` | California | | `USA-STATE` | `CO` | Colorado | | `USA-STATE` | `CT` | Connecticut | | `USA-STATE` | `DE` | Delaware | | `USA-STATE` | `FL` | Florida | | `USA-STATE` | `GA` | Georgia | | `USA-STATE` | `HI` | Hawaii | | `USA-STATE` | `ID` | Idaho | | `USA-STATE` | `IL` | Illinois | | `USA-STATE` | `IN` | Indiana | | `USA-STATE` | `IA` | Iowa | | `USA-STATE` | `KS` | Kansas | | `USA-STATE` | `KY` | Kentucky | | `USA-STATE` | `LA` | Louisiana | | `USA-STATE` | `ME` | Maine | | `USA-STATE` | `MD` | Maryland | | `USA-STATE` | `MA` | Massachusetts | | `USA-STATE` | `MI` | Michigan | | `USA-STATE` | `MN` | Minnesota | | `USA-STATE` | `MS` | Mississippi | | `USA-STATE` | `MO` | Missouri | | `USA-STATE` | `MT` | Montana | | `USA-STATE` | `NE` | Nebraska | | `USA-STATE` | `NV` | Nevada | | `USA-STATE` | `NH` | New Hampshire | | `USA-STATE` | `NJ` | New Jersey | | `USA-STATE` | `NM` | New Mexico | | `USA-STATE` | `NY` | New York | | `USA-STATE` | `NC` | North Carolina | | `USA-STATE` | `ND` | North Dakota | | `USA-STATE` | `OH` | Ohio | | `USA-STATE` | `OK` | Oklahoma | | `USA-STATE` | `OR` | Oregon | | `USA-STATE` | `PA` | Pennsylvania | | `USA-STATE` | `RI` | Rhode Island | | `USA-STATE` | `SC` | South Carolina | | `USA-STATE` | `SD` | South Dakota | | `USA-STATE` | `TN` | Tennessee | | `USA-STATE` | `TX` | Texas | | `USA-STATE` | `UT` | Utah | | `USA-STATE` | `VT` | Vermont | | `USA-STATE` | `VA` | Virginia | | `USA-STATE` | `WA` | Washington | | `USA-STATE` | `WV` | West Virginia | | `USA-STATE` | `WI` | Wisconsin | | `USA-STATE` | `WY` | Wyoming | | `USA-STATE` | `DC` | District of Columbia | | `USA-STATE` | `PR` | Puerto Rico | | `USA-STATE` | `GU` | Guam | | `USA-STATE` | `VI` | U.S. Virgin Islands | | `USA-STATE` | `AS` | American Samoa | | `USA-STATE` | `MP` | Northern Mariana Islands | | `CAN-PROVINCE` | `AB` | Alberta | | `CAN-PROVINCE` | `BC` | British Columbia | | `CAN-PROVINCE` | `MB` | Manitoba | | `CAN-PROVINCE` | `NB` | New Brunswick | | `CAN-PROVINCE` | `NL` | Newfoundland and Labrador | | `CAN-PROVINCE` | `NS` | Nova Scotia | | `CAN-PROVINCE` | `ON` | Ontario | | `CAN-PROVINCE` | `PE` | Prince Edward Island | | `CAN-PROVINCE` | `QC` | Quebec | | `CAN-PROVINCE` | `SK` | Saskatchewan | | `CAN-PROVINCE` | `NT` | Northwest Territories | | `CAN-PROVINCE` | `NU` | Nunavut | | `CAN-PROVINCE` | `YT` | Yukon |
> **Info** > > The `timestamp` in the example uses a space separator and a `Z` suffix > (`YYYY-MM-DD HH:mm:ss.SSSZ`) and should be treated as UTC. If you need to parse > it programmatically, normalize it yourself (for example, replace the space with > `T`) rather than assuming a strict ISO-8601 string. ## Delivery mechanics * Deliveries are HTTP **`POST`** requests. * The header **`Content-Type: application/json`** is set, with the JSON body shown above. * Your endpoint should **respond quickly with a `2xx` status** to acknowledge receipt. For details on delivery status, retries, and timeouts, see [Test & monitor](testing). Some production delivery behavior (retry policy, production timeouts, source IP ranges) is not yet documented. Contact [support](https://www.zip.tax/contact) if you need those specifics for your integration. ## Next step #### [Verify & secure deliveries](verify) Use the signing secret to confirm requests come from Ziptax.