Public API v1 — Webhooks
Public API v1 — Webhooks

Register a webhook

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.

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

Request body

urlstring required

HTTPS URL to receive webhook POST requests. Must be publicly accessible.

eventsstring[]

Event types to subscribe to. Available: interview.transcribed, interview.analyzed, interview.failed, candidate_feedback.completed

descriptionstring nullable

Optional description for this webhook.

Example request

{
  "url": "https://yourapp.com/webhooks/betterhire",
  "events": [
    "interview.analyzed",
    "interview.failed"
  ],
  "description": "Production webhook for ATS integration"
}

Response

Successful Response

idstring required

Webhook ID.

urlstring required

Webhook URL.

eventsstring[] required

Subscribed event types.

enabledboolean required

Whether this webhook is active.

descriptionstring nullable
secretstring nullable

Signing secret (only returned on creation). Use to verify HMAC-SHA256 signature in X-BetterHire-Signature header.

created_atstring required

ISO 8601 creation timestamp.

Changes

No recorded changes to this operation across all 1 revision of this API.