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

# Register a scan webhook endpoint

`POST /api/v1/webhooks`

## Request

- Base URL: `https://app.qrtap.kg`
- URL: `https://app.qrtap.kg/api/v1/webhooks`
- Auth: HTTP bearer

Registers an HTTPS endpoint that receives a POST for every scan of your organization's codes (see the `scan` webhook definition). The response contains `signing_secret` exactly once — store it to verify the `X-QRTap-Signature` header on deliveries.

## Request body

- object
  - `url` string, uri, required: Delivery URL. Must be https://.

## Response `201`

Endpoint registered. `signing_secret` is shown only in this response.

- WebhookEndpointCreated
  - `id` string, uuid, required
  - `url` string, uri, required
  - `active` boolean, required
  - `signing_secret` string, required: whsec_-prefixed secret for verifying X-QRTap-Signature. Shown only once.
  - `created_at` string, date-time, required

## Other responses

- `400`: `invalid_request` (see `detail`) or `invalid_url` (not https).
- `401`: Missing, invalid or revoked API key.
- `402`: The capability exists but the workspace plan does not open it (bulk creation, scan webhooks, writing smart rules). Deliberately 402 and not 403: the request is valid and the identical call succeeds once the plan is upgraded — nothing in the integration has to change. Does not spend daily quota.

---

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