---
title: "Register a webhook"
method: POST
path: "/api/public/v1/webhooks"
tags: ["Public API v1 — Webhooks", "Public API v1 — Webhooks"]
---

# Register a webhook

`POST /api/public/v1/webhooks`

## Request

- Base URL: `https://api.thebetterhire.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.thebetterhire.ai/api/public/v1/webhooks`
- Auth: HTTP bearer

Register a URL to receive POST notifications when interview events occur. Returns a signing secret — store it securely. All webhook payloads are signed with HMAC-SHA256 using this secret.

## Request body

- WebhookCreateRequest: Register a webhook endpoint to receive interview event notifications.
  - `url` string, required: HTTPS URL to receive webhook POST requests. Must be publicly accessible.
  - `events` string[]: Event types to subscribe to. Available: interview.transcribed, interview.analyzed, interview.failed, candidate_feedback.completed
  - `description` string, nullable: Optional description for this webhook.

## Response `201`

Successful Response

- WebhookResponse: Registered webhook endpoint.
  - `id` string, required: Webhook ID.
  - `url` string, required: Webhook URL.
  - `events` string[], required: Subscribed event types.
  - `enabled` boolean, required: Whether this webhook is active.
  - `description` string, nullable
  - `secret` string, nullable: Signing secret (only returned on creation). Use to verify HMAC-SHA256 signature in X-BetterHire-Signature header.
  - `created_at` string, required: ISO 8601 creation timestamp.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/thebetterhire/apis/interanalysis-b2b-api.md) · [All operations](https://skmtc.dev/thebetterhire/apis/interanalysis-b2b-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thebetterhire/apis/interanalysis-b2b-api/revisions/c8ad03e900ea?raw)