---
title: "Add Webhook"
method: POST
path: "/monitoring/webhooks"
tags: ["monitoring"]
---

# Add Webhook

`POST /monitoring/webhooks`

## Request

- Base URL: `https://api.licenscheck.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.licenscheck.com/monitoring/webhooks`
- Auth: none declared

Send this key's monitoring events to an https URL, each delivery signed.

The response carries the webhook's signing secret, shown only this once.
Each delivery is a POST of one event (the same JSON as the events feed)
with `Licenscheck-Event-Id` and `Licenscheck-Signature: t=<unix>,v1=<hex>`,
where v1 is the HMAC-SHA256 of `"<t>.<body>"` under the secret. A delivery
that isn't answered with a 2xx within 10 seconds is retried after 5 and 30
minutes, then 2, 6 and 24 hours; a webhook with no 2xx for 3 days is
disabled. The events feed keeps every event either way.

Args:
    body: The URL.
    api_key_id: Injected: the caller's key.
    monitoring: Injected `MonitoringRepository`.
    resolve: Injected DNS lookup, for the address check.

Returns:
    The webhook and its secret.

Raises:
    HTTPException: 409 at the webhook limit, 422 for an unusable URL, 503 when webhooks are off.

## Request body

- WebhookIn: Body for POST /monitoring/webhooks.
  - `url` string, required: An https URL on the public internet that accepts POSTed JSON events.

## Response `201`

Successful Response

- WebhookCreatedOut: Response for POST /monitoring/webhooks: the webhook, and its signing secret, shown only this once.
  - `id` string, uuid, required: The webhook's ID.
  - `url` string, required: Where events are POSTed.
  - `created_at` string, date-time, required: When it was added.
  - `last_success_at` string, date-time, nullable, required: The last time it answered a delivery with a 2xx, if ever.
  - `secret` string, required: Verifies the `Licenscheck-Signature` header on each delivery. Shown only now: store it. Delete the webhook and add it again for a new one.

## Other responses

- `401`: No API key, or one that's wrong or revoked.
- `403`: A free key: monitoring needs a paid plan.
- `409`: The key already has 3 webhooks.
- `422`: The URL isn't https, or doesn't reach a public address.
- `503`: Webhooks aren't available yet.

---

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