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

# Register a webhook endpoint

`POST /v1/me/webhooks`

## Request

- Base URL: `https://api.farofinance.app`
- URL: `https://api.farofinance.app/v1/me/webhooks`
- Auth: none declared

Register an HTTPS endpoint to receive signed `artifact.flagged` events. The response includes the signing `secret` **once** — store it now; verify incoming deliveries with the `X-Faro-Signature` header.

## Request body

- WebhookCreateIn: Register a receiver for the caller's key.
  - `url` string, required: HTTPS endpoint Faro POSTs signed events to.
  - `events` string[], nullable: Events to subscribe to. Defaults to `["artifact.flagged"]`.
  - `label` string, nullable: Optional human label for this endpoint.

## Response `201`

Successful Response

- WebhookCreated: Creation response — includes the signing secret, shown exactly once.
  - `id` string, required: Endpoint id, e.g. `whk_…`.
  - `url` string, required: Where events are delivered.
  - `events` string[], required: Subscribed event types.
  - `active` boolean, required: Whether deliveries are currently sent.
  - `label` string, nullable: Optional human label.
  - `created_at` string, date-time, required: When the endpoint was registered.
  - `secret` string, required: HMAC signing secret (`whsec_…`). Store it now — it is never shown again.

## Other responses

- `401`: Missing or invalid API key.
- `403`: Admin or dev-mode credentials cannot use dashboard routes.
- `422`: Validation Error

---

[API](https://skmtc.dev/farofinance/apis/faro.md) · [All operations](https://skmtc.dev/farofinance/apis/faro/llms.txt) · [OpenAPI document](https://skmtc.dev/farofinance/apis/faro/revisions/205cdf54420b?raw)