Webhooks

Events reference

The event catalog, payload schema, and delivery mechanics
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

EventDescription
rate.updatedSent 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}

Field reference

FieldTypeDescription
eventstringThe event type, e.g. rate.updated.
timestampstringWhen the event was generated (UTC).
dataobjectEvent-specific payload.
data.rateUpdateDetail.localitystringThe kind of tax authority that changed. One of USA-STATE or CAN-PROVINCE. See Tax authority values.
data.rateUpdateDetail.codestringThe two-letter code of the state, province, or territory within that locality (example value: CA). See Tax authority values.

locality and code identify which authority changed. To get the new rate values, call the Ziptax rate API for that authority. 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:

LocalityMeaning
USA-STATEA U.S. state, the District of Columbia, or a U.S. territory.
CAN-PROVINCEA 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)
LocalityCodeDescription
USA-STATEALAlabama
USA-STATEAKAlaska
USA-STATEAZArizona
USA-STATEARArkansas
USA-STATECACalifornia
USA-STATECOColorado
USA-STATECTConnecticut
USA-STATEDEDelaware
USA-STATEFLFlorida
USA-STATEGAGeorgia
USA-STATEHIHawaii
USA-STATEIDIdaho
USA-STATEILIllinois
USA-STATEINIndiana
USA-STATEIAIowa
USA-STATEKSKansas
USA-STATEKYKentucky
USA-STATELALouisiana
USA-STATEMEMaine
USA-STATEMDMaryland
USA-STATEMAMassachusetts
USA-STATEMIMichigan
USA-STATEMNMinnesota
USA-STATEMSMississippi
USA-STATEMOMissouri
USA-STATEMTMontana
USA-STATENENebraska
USA-STATENVNevada
USA-STATENHNew Hampshire
USA-STATENJNew Jersey
USA-STATENMNew Mexico
USA-STATENYNew York
USA-STATENCNorth Carolina
USA-STATENDNorth Dakota
USA-STATEOHOhio
USA-STATEOKOklahoma
USA-STATEOROregon
USA-STATEPAPennsylvania
USA-STATERIRhode Island
USA-STATESCSouth Carolina
USA-STATESDSouth Dakota
USA-STATETNTennessee
USA-STATETXTexas
USA-STATEUTUtah
USA-STATEVTVermont
USA-STATEVAVirginia
USA-STATEWAWashington
USA-STATEWVWest Virginia
USA-STATEWIWisconsin
USA-STATEWYWyoming
USA-STATEDCDistrict of Columbia
USA-STATEPRPuerto Rico
USA-STATEGUGuam
USA-STATEVIU.S. Virgin Islands
USA-STATEASAmerican Samoa
USA-STATEMPNorthern Mariana Islands
CAN-PROVINCEABAlberta
CAN-PROVINCEBCBritish Columbia
CAN-PROVINCEMBManitoba
CAN-PROVINCENBNew Brunswick
CAN-PROVINCENLNewfoundland and Labrador
CAN-PROVINCENSNova Scotia
CAN-PROVINCEONOntario
CAN-PROVINCEPEPrince Edward Island
CAN-PROVINCEQCQuebec
CAN-PROVINCESKSaskatchewan
CAN-PROVINCENTNorthwest Territories
CAN-PROVINCENUNunavut
CAN-PROVINCEYTYukon

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.