Events reference

Available onProEnterprise

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.

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`

1 {
2   "event": "rate.updated",
3   "timestamp": "2026-06-11 00:00:00.000Z",
4   "data": {
5     "rateUpdateDetail": {
6       "locality": "USA-STATE",
7       "code": "CA"
8     }
9   }
10 }

Notification granularity

Your account’s 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

1 {
2   "event": "rate.updated",
3   "timestamp": "2026-06-11 00:00:00.000Z",
4   "data": {
5     "rateUpdateDetail": {
6       "locality": "USA-STATE",
7       "code": "CA",
8       "postalcodeList": ["92101", "92103", "92130"]
9     }
10   }
11 }

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.
`data.rateUpdateDetail.code`	string	The two-letter code of the state, province, or territory within that locality (example value: `CA`). See Tax authority values.
`data.rateUpdateDetail.postalcodeList`	array of strings	The postal codes affected by the change. Included only when your account’s Granularity Level is Postal code (Enterprise plans only). See Notification granularity.

locality, code, and postalcodeList identify where rates changed. To get the new rate values, call the Ziptax rate API 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.

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

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. Some production delivery behavior (retry policy, production timeouts, source IP ranges) is not yet documented. Contact support if you need those specifics for your integration.

Next step

Verify & secure deliveries

Use the signing secret to confirm requests come from Ziptax.