---
title: "Subscribe to change events (Pro+ · requires an API key)"
method: POST
path: "/webhooks"
---

# Subscribe to change events (Pro+ · requires an API key)

`POST /webhooks`

## Request

- Base URL: `https://ai-law-tracker.com/api/v1`
- URL: `https://ai-law-tracker.com/api/v1/webhooks`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Create a webhook. When a matching legal record change is observed, an HMAC-SHA256-signed POST is delivered to target_url. The signing_secret is returned ONCE in this response. Verify each delivery (see x-webhooks). TIER-GATING: Pro+ only (Free/Developer allowance = 0 → 403 tier_upgrade_required). Per-key subscription cap: Pro 3, Business 25, Enterprise unlimited.

## Request body

- object
  - `target_url` string, required: Public HTTPS endpoint.
  - `events` string[]: Default: law.created, law.updated.
  - `scope` 'state' | 'federal' | 'eu' | 'global': Optional filter.
  - `jurisdiction` string: Optional exact-slug filter.

## Response `201`

Created (includes signing_secret, shown once).

- object
  - `data` Webhook: A change-notification subscription.
    - `id` string, uuid
    - `target_url` string: HTTPS endpoint that receives signed POSTs.
    - `events` string[]
    - `scope` 'state' | 'federal' | 'eu' | 'global', nullable: Optional filter — only changes in this scope.
    - `jurisdiction` string, nullable: Optional filter — only changes for this jurisdiction slug.
    - `active` boolean
    - `failure_count` integer: Consecutive failed deliveries; the webhook auto-disables at 10.
    - `disabled_at` string, date-time, nullable
    - `disabled_reason` string, nullable
    - `last_delivery_at` string, date-time, nullable
    - `created_at` string, date-time

## Other responses

- `400`: Invalid target_url or events
- `401`: API key required
- `409`: Per-key webhook limit reached
- `503`: Webhooks not enabled yet

---

[API](https://skmtc.dev/ai-law-tracker/apis/ai-law-tracker-public-laws-api.md) · [All operations](https://skmtc.dev/ai-law-tracker/apis/ai-law-tracker-public-laws-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ai-law-tracker/apis/ai-law-tracker-public-laws-api/revisions/25403268a853?raw)