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

# Register a webhook

`POST /api/v1/webhooks`

## Request

- Base URL: `https://numonic.ai`
- URL: `https://numonic.ai/api/v1/webhooks`
- Auth: API key in header `x-api-key`

Subscribe to Numonic events (asset.created, collection.published, pipeline.completed, etc.) via HTTP callback. asset.created is delivered once an uploaded asset has finished processing. Works with a session or an API key with the write scope; an API key registers webhooks for its own workspace only. Returns an HMAC-SHA256 signing secret for payload verification — this secret is shown only once, so store it securely.

## Headers

- `X-Tenant-ID` string, uuid, required: Target tenant UUID. Required when API key has access to multiple tenants.

## Request body

- CreateWebhookRequest: Request body for creating a new webhook subscription
  - `name` string, required: Human-friendly name for this webhook subscription
  - `description` string: Optional description of this webhook subscription
  - `url` string, uri, required: Destination URL that will receive webhook POST requests
  - `events` string[], required: List of event names to subscribe to (e.g. "asset.created")
  - `enabled` boolean: Whether this webhook subscription is active
  - `timeout_ms` integer: Timeout for each webhook delivery attempt in milliseconds
  - `custom_headers` object: Optional custom HTTP headers sent with each webhook request

## Response `201`

Webhook registered. HMAC secret returned (store securely — shown once).

- WebhookCreatedResponse
  - `id` string, required
  - `name` string, required
  - `url` string, uri, required
  - `events` string[], required
  - `enabled` boolean, required
  - `secret` string, required: HMAC-SHA256 signing secret — shown only once. Store securely.
  - `created_at` string, required

## Other responses

- `400`: Validation failed or invalid URL (SSRF protection)
- `409`: Webhook subscription already exists

---

[API](https://skmtc.dev/numonic/apis/numonic-api.md) · [All operations](https://skmtc.dev/numonic/apis/numonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numonic/apis/numonic-api/revisions/6c559bef1e35?raw)