---
title: "Create a webhook subscription"
method: POST
path: "/v1/webhooks/"
tags: ["Webhooks"]
---

# Create a webhook subscription

`POST /v1/webhooks/`

Register a new webhook subscription for property events. The endpoint URL is validated on creation — it must be reachable and return a 2xx response. Currently supports `deed.*` events scoped to Texas counties.

## Request body

- CreateWebhookRequestDto — Request body for creating a webhook subscription.
  - `url` string, required — HTTPS URL where webhook notifications will be delivered via POST. Must use HTTPS.
  - `name` string, nullable — Optional human-readable label for identifying this subscription (max 255 characters).
  - `event_type` string, required — Event type to subscribe to, in `category.*` format. Currently only `deed.*` is supported.
  - `region` string, required — Geographic region in `type:value` format. Supported types: `state:{code}` (e.g., `state:tx`) for an entire state, or `county:{state}.{name}` (e.g., `county:tx.travis`) / `county:{fips}` (e.g., `county:48453`) for a single county. Currently only Texas and its counties are supported. Use the Regions API to discover valid values: `GET /v1/regions/states` and `GET /v1/regions/states/{state}/counties`.

## Response `201`

Webhook created successfully

- DetailResponseDtoWebhookResponseDto
  - `result` WebhookResponseDto, required — Webhook subscription response object.
    - `id` string, required — Unique identifier for the webhook subscription.
    - `url` string, required — HTTPS endpoint URL where notifications are delivered.
    - `name` string, nullable — Human-readable label for the subscription.
    - `event_type` string, required — The event type this webhook is subscribed to, in `category.*` format. Currently only `deed.*` is supported.
    - `region` string, required — Geographic region this webhook is scoped to, in `type:value` format. Currently only Texas and its counties are supported.
    - `status` string, required — Current status of the webhook. `active` webhooks receive event notifications; `inactive` webhooks are paused and do not receive deliveries.
    - `created_at` string, required — Timestamp when the webhook was created (ISO 8601).
    - `updated_at` string, required — Timestamp of the last modification (ISO 8601).

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `409` — Conflict
- `422` — Unprocessable Content
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.dev/whitepages/apis/whitepages-api-reference.md) · [All operations](https://skmtc.dev/whitepages/apis/whitepages-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/whitepages/whitepages-api-reference/revisions/c27a0cd8718f/schema)