Webhook endpoints

Add a webhook endpoint

POST/api/v1/webhook_endpoints

Registers a URL to send events to. The URL must be https, with no user name, password or fragment, to a host name (not an IP address) that resolves to a public address, in test mode as well as live mode. Leave out event_types to receive every type. An organization can have at most 10 endpoints in a mode. The response carries the signing secret (secret). It is shown only in this response and cannot be read again: store it now. A request repeated with the same Idempotency-Key gets the stored reply without the secret (secret_available is false): rotate the secret to get a new one.

Needs a key with submit permission.

Request

Headers

Headers
Name	Type	Required	Description
Idempotency-Key	string	required	Makes the request safe to repeat: a request with the same key and body returns the first answer (the reply has an idempotent-replayed header), and the same key with a different request is refused. 1 to 255 printable characters; a UUID is a good choice.At least 1 character.At most 255 characters.Matches `^[\x21-\x7e]{1,255}$`.

Body

Body
Name	Type	Required	Description
url	string	required	Where events are sent: an https URL to a host name that resolves to a public address.At most 2048 characters.
description	string	optional	A note for yourself.At most 200 characters.
event_types	array of string	optional	The event types to send. Leave out for every type.At most 19 items.Each item is one of: `eligibility.completed`, `api_key.created`, `api_key.revoked`, `claim.validated`, `claim.needs_attention`, `claim.queued`, `claim.submitted`, `claim.accepted`, `claim.rejected`, `claim.status_updated`, `claim.voided`, `batch.acknowledged`, `attachment.completed`, `payer_request.received`, `era.received`, `claim.paid`, `claim.denied`, `claim.payment_reversed`, `predetermination.returned`.

Response

The endpoint, with its signing secret. Status 200.

Response fields
Name	Type	Description
id	string	An ID that starts with whe_.
object	string	Always `webhook_endpoint`.
url	string
description	string
event_types	array of string or null	The event types sent to this endpoint; null for every type.Each item is one of: `eligibility.completed`, `api_key.created`, `api_key.revoked`, `claim.validated`, `claim.needs_attention`, `claim.queued`, `claim.submitted`, `claim.accepted`, `claim.rejected`, `claim.status_updated`, `claim.voided`, `batch.acknowledged`, `attachment.completed`, `payer_request.received`, `era.received`, `claim.paid`, `claim.denied`, `claim.payment_reversed`, `predetermination.returned`.
status	string	One of: `enabled`, `disabled`.
mode	string	One of: `test`, `live`.
created_at	string (date-time)
secret	string	The signing secret (whsec_...). Shown only in the response that made it: store it now. Absent when secret_available is false.
secret_available	boolean	False in the stored reply an Idempotency-Key replay returns: the secret is never stored for replay. Rotate the secret to get a new one.

Errors

Errors
HTTP status	Code	What it means
401	UNAUTHORIZED	A valid API key is required. Send it as "Authorization: Bearer <key>".
403	PERMISSION_DENIED	This API key is not allowed to do that.
422	INVALID_REQUEST	The request is not valid.
400	IDEMPOTENCY_KEY_REQUIRED	POST and PATCH requests need an Idempotency-Key header.
422	IDEMPOTENCY_KEY_REUSED	That Idempotency-Key was already used with a different request.
409	IDEMPOTENCY_KEY_IN_USE	A request with that Idempotency-Key is still running. Retry shortly.
413	PAYLOAD_TOO_LARGE	The request body is larger than 1 MB.
504	TIMEOUT	The request took too long to finish. It may still have taken effect: look it up before sending it again with a new Idempotency-Key. What it made is found with GET /api/v1/eligibility?request_id=<this request_id>, and the same filter on /api/v1/claims and /api/v1/attachments (a key with read permission).
500	INTERNAL	Something went wrong on our side. Quote the request ID if you contact us.

Example

Example request

Shell

curl -X POST "https://sandbox.myclaimhouse.com/api/v1/webhook_endpoints" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://hooks.example.com/claimhouse",
  "description": "Billing system",
  "event_types": [
    "eligibility.completed"
  ]
}'

Example response: 200

JSON

{
  "id": "whe_01JM000000E008000000000021",
  "object": "webhook_endpoint",
  "url": "https://hooks.example.com/claimhouse",
  "description": "Billing system",
  "event_types": [
    "eligibility.completed"
  ],
  "status": "enabled",
  "mode": "test",
  "created_at": "2026-03-10T15:00:00.000000+00:00",
  "secret": "whsec_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEE",
  "secret_available": true
}