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

# Register a webhook endpoint.

`POST /v1/webhooks`

## Request

- Base URL: `https://api.inboxy.net`
- URL: `https://api.inboxy.net/v1/webhooks`
- Auth: HTTP bearer

Requires `manage` scope on a paid plan (`paid_feature`, 403, on free). Gated by the plan's `webhook_limit` (`cap_reached`, 403, body carries `used`/`limit`). `url` must be HTTPS and is SSRF-checked (`invalid_url`, 400) before the row is created. The response's `secret` is shown once — store it; it signs the `X-Inboxy-Signature` header on every delivery.

## Request body

- WebhookCreate
  - `url` string, uri, required: HTTPS only; must not resolve to a private/reserved address.

## Response `201`

Created.

- Webhook
  - `id` string, uuid, required
  - `url` string, uri, required
  - `enabled` boolean, required: Auto-disabled after 5 consecutive delivery failures.
  - `consecutive_failures` integer, required
  - `last_status` string, nullable
  - `last_delivery_at` integer, nullable: Unix seconds.
  - `created_at` integer, required
  - `secret` string: Plaintext signing secret. Only present in the response to `POST /v1/webhooks` and `POST /v1/webhooks/{id}/rotate-secret` — never returned by `GET /v1/webhooks`.

## Other responses

- `400`: Malformed request.
- `403`: Token lacks the required scope.

---

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