---
title: "Create Webhook"
method: POST
path: "/api/v1/webhooks"
tags: ["webhooks"]
---

# Create Webhook

`POST /api/v1/webhooks`

## Request

- Base URL: `https://api.billcommons.org`
- URL: `https://api.billcommons.org/api/v1/webhooks`
- Auth: none declared

## Request body

- WebhookCreateRequest
  - `url` string, required
  - `email` string, required
  - `kind` string, required: topic | jurisdiction | bills
  - `target` string, required: topic: a topic slug. jurisdiction: a jurisdiction abbreviation. bills: comma-separated bill UUIDs (at most 64, and the combined url/kind/target/event_kinds must fit a shared byte budget -- see docs/api/webhooks.md).
  - `jurisdiction` string, nullable: Only used with kind='topic', to scope the topic to one state, e.g. 'FL'.
  - `event_kinds` string, nullable: Comma-separated subset of created,status,actions,sponsors,text,metadata,votes. Omit for all kinds.

## Response `201`

Successful Response

- WebhookCreateResponse
  - `id` string, uuid, required
  - `manage_token` string, required: Shown once. Bearer token for GET/DELETE/reactivate -- store it now.
  - `signing_secret` string, required: HMAC key for verifying delivery signatures.
  - `verified` boolean, required
  - `note` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/billcommons/apis/bill-commons-api.md) · [All operations](https://skmtc.dev/billcommons/apis/bill-commons-api/llms.txt) · [OpenAPI document](https://skmtc.dev/billcommons/apis/bill-commons-api/revisions/bfb8cd50a317?raw)