Real-time Webhooks

Webhooks allow your application to receive real-time HTTP POST notifications whenever an Ohio sales tax event occurs. Instead of continuously polling the Rate API, our event dispatcher notifies your servers within seconds of state publication.

Supported Events

Event Name	Trigger
`rate.changed`	An Ohio county sales tax rate change becomes legally effective.
`rate.announced`	Ohio Department of Taxation officially releases an upcoming quarter's rate schedule.
`certificate.expiring`	A customer exemption certificate is 30 days or 7 days from statutory expiry.
`filing.due`	Upcoming filing deadline reminder for Ohio UST-1 sales tax returns.
`*`	Wildcard: subscribes to all platform events.

Registering Webhooks

You can register endpoints via the API Keys & Webhooks dashboard or programmatically via the API:

curl -X POST "https://app.ohiosalestaxcalculator.com/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourdomain.com/webhooks/ohio-tax",
    "events": ["rate.changed", "certificate.expiring"]
  }'

Response (`201 Created`)

{
  "webhook": {
    "id": "wh_90b1c2_34ef",
    "url": "https://api.yourdomain.com/webhooks/ohio-tax",
    "secret": "whsec_0123456789abcdef0123456789abcdef",
    "events": ["rate.changed", "certificate.expiring"],
    "status": "active",
    "created_at": "2026-10-03T18:00:00Z"
  },
  "message": "Webhook registered successfully. Save the signing secret to verify payload signatures."
}

Event Payload Format

Every webhook payload delivered to your destination URL follows standard event envelope formatting:

{
  "id": "evt_test_7f9c21b0",
  "type": "rate.changed",
  "created_at": "2026-10-03T18:00:00Z",
  "data": {
    "county": "Warren",
    "county_slug": "warren",
    "old_rate": 0.0675,
    "new_rate": 0.0725,
    "effective_date": "2026-10-01",
    "lead_days": 0,
    "days_until": 0
  }
}

Standard Headers

Every webhook dispatch includes:

X-Webhook-ID: Unique event identifier (e.g. evt_...).
X-Webhook-Timestamp: Integer unix epoch timestamp.
X-Webhook-Signature: HMAC-SHA256 signature in t={timestamp},v1={hex_hash} format.
Content-Type: application/json.
User-Agent: OhioSalesTaxCalculator-Webhook/1.0.