Webhooks

Get pushed an event when a followed bill changes — signed, retried, and idempotent. No polling required.

Webhooks let you react to legislative activity in real time instead of polling the API. Register an HTTPS endpoint and we'll POST a JSON event when something you subscribe to changes.

Event payload

POST https://your-app.example.com/hooks/ocp
Content-Type: application/json
X-Capitol-Signature: <hmac-sha256>
X-Capitol-Timestamp: 1750861200
X-Capitol-Idempotency-Key: <delivery-id>

{
  "id": 987,
  "event": "bill.action",
  "data": {
    "bill_id": 1,
    "identifier": "HR 1",
    "description": "Referred to the Committee on Energy and Commerce"
  }
}

Event types

bill.introduced — a bill you track was introduced
bill.action — a new action landed on the bill
bill.status_changed — the bill's status changed
vote.recorded — a roll-call vote was recorded

Subscribe to specific events or use * to receive them all.

Verifying & responding

Each delivery is signed with HMAC-SHA256 using your subscription secret (it starts with whsec_), so you can confirm it came from us. The X-Capitol-Idempotency-Key lets you de-duplicate retries. Respond 2xx quickly; a 4xx is treated as permanent (no retry), while 5xx and 429 are retried with exponential backoff. Webhooks are available on the Business tier and up — tell us what you're building.