---
title: "Register a webhook endpoint"
method: POST
path: "/v1/webhooks"
---

# Register a webhook endpoint

`POST /v1/webhooks`

## Request

- Base URL: `https://api.trackingmcp.com`
- URL: `https://api.trackingmcp.com/v1/webhooks`
- Auth: HTTP bearer

Register an https:// endpoint to receive shipment events for your organisation. Accounts have an active-endpoint limit (three by default); inactive endpoints do not consume a slot. `event_types` is filtered against the supported list on the way in: an unrecognised name is dropped silently rather than rejected, so send only values from the enum and read the returned `event_types` back to confirm what was stored. An empty or omitted `event_types` stores an empty list. Every type in the enum has a live producer.

## Request body

- object
  - `url` string, uri, required: Destination endpoint. Must start with https://.
  - `event_types` WebhookEventType[]: Events to receive. Names outside the enum are discarded.
  - `description` string: Free-text label for your own bookkeeping.

## Response `201`

Endpoint registered. THE `secret` IS RETURNED ONCE, HERE, AND NEVER AGAIN — no later endpoint returns it and it cannot be re-read. Store it now: it is the HMAC key you verify each delivery's signature against. Losing it means deleting the endpoint and registering a new one.

- object
  - `ok` true
  - `data` object: A registered webhook endpoint. The signing secret is NOT part of this shape: it is returned once, on create, and never again. `failure_count` and `last_delivery_at` are present on the list and detail responses but not on the create or update responses.
    - `id` string, uuid
    - `url` string, uri
    - `event_types` WebhookEventType[]: The stored subscription, after unrecognised names were filtered out.
    - `description` string, nullable
    - `active` boolean
    - `failure_count` integer: Consecutive delivery failures. Reset to 0 by a PATCH setting active: true.
    - `last_delivery_at` string, date-time, nullable
    - `created_at` string, date-time
    - `secret` string, required: Signing secret. Returned only on this response.

## Other responses

- `400`: `INVALID_URL` — url missing or not an https:// URL.
- `401`: Missing or invalid API key.
- `409`: `WEBHOOK_ENDPOINT_LIMIT` — the account has reached its active webhook endpoint limit.
- `500`: `INTERNAL_ERROR` — the endpoint could not be stored.

---

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