---
title: Webhook subscriptions
description: Register and list outbound event subscriptions through the public API.
---

The public contract exposes webhook subscription management at `/api/v1/webhooks`:

- `GET /api/v1/webhooks` lists the subscriptions visible to a tenant administrator. It uses the standard `$top` and `$skip` pagination envelope.
- `POST /api/v1/webhooks` creates a subscription with an `eventType`, callback `url`, secret of at least 16 characters, and optional `active` flag.
- Both operations require the `webhooks:admin` scope and the tenant-admin permission gate.

The current event catalog is `matter.created`, `relation.created`, `hour.created`, `task.created`, and `invoice.sent`. Subscription responses never return the supplied secret.

The committed OpenAPI does not yet publish delivery-signature headers, retry timing, or a public update/revoke operation. Do not infer those details from internal code; treat them as outside the published contract until they appear in OpenAPI.

[Open the published OpenAPI JSON](/openapi.json) for the exact request and response schemas, or read the [developer API map](/developers/public-api).