post/v2/webhook-endpoints

Register a webhook endpoint

Operation: createWebhookEndpoint
Authentication: API key

Every delivery is signed with `X-Haavisa-Signature: t=<unix>,v1=<hex>`, an HMAC-SHA256 over `{timestamp}.{body}` using the endpoint secret. **Verify the timestamp as well as the signature** — a signature check alone proves authenticity, not freshness, and would accept a replay of a captured delivery. `X-Haavisa-Delivery` is the id to deduplicate on: delivery is at-least-once, so the same event will occasionally arrive twice.

Request

Body

urlstringrequired

HTTPS required outside development. A delivery carries an applicant’s details and the outcome of their application.

descriptionstring

eventsstring[]required

Responses

201Registered. The signing secret is returned once.

endpointWebhookEndpointrequired

secretstringrequired

The HMAC signing secret. Unlike an API key this is recoverable — we sign every delivery with it — but a partner who never sees it cannot verify anything we send.

warningstringrequired

400The request body or query failed validation.

errorobjectrequired

401No key, an unknown key, a revoked key, or a key whose tenant is not active. All four return an identical body on purpose: distinguishing them would let a caller discover which partners we have.

errorobjectrequired

403The key is valid but lacks the scope, or it asked for a scope it does not itself hold.

errorobjectrequired

404Not found, or not yours. A resource belonging to another tenant answers 404 rather than 403, because 403 would confirm the record exists.

errorobjectrequired

Example

curl

curl -X POST https://api.haavisa.com/v2/webhook-endpoints \
  -H "Authorization: Bearer $HAAVISA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "<url>",
    "events": []
  }'

More in Webhooks

Something unclear? The eligibility guide explains the model behind the answers; the errors guide covers the envelope.