Webhooks
Create Webhook
Register a URL that receives webhook events
POST
/
api
/
v1
/
webhooks
curl --request POST \
--url https://anivahealth.com/api/v1/webhooks \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://partner.example.com/webhooks/aniva",
"enabled_events": [
"appointment.confirmed",
"appointment.results.completed",
"home_kit_order.results.completed"
],
"alert_emails": [
"ops@partner.example.com"
],
"description": "Production"
}'
{
"secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw8L0qsE2bkS4=",
"id": "4a6c8e0f-2b4d-4f6a-8c0e-2a4c6e8f0b1d",
"url": "https://partner.example.com/webhooks/aniva",
"description": "Production",
"enabled_events": [
"appointment.confirmed",
"appointment.results.completed",
"home_kit_order.results.completed"
],
"alert_emails": ["ops@partner.example.com"],
"status": "enabled",
"disabled_at": null,
"disabled_reason": null,
"failing_since": null,
"previous_secret_expires_at": null,
"created_at": "2026-10-15T08:00:00.000Z",
"updated_at": "2026-10-15T08:00:00.000Z"
}
{
"error": "url must use https"
}
{
"error": "An API key can own at most 5 webhooks"
}
Register an HTTPS URL that receives webhook events. Your API key owns the
webhook. It receives an event only for objects your key can read. An API key can own at most 5
webhooks.
Requires the
webhooks_manage scope.Request
Body parameters
string
required
HTTPS URL on port 443 with a public host and no credentials. Aniva does not follow redirects.
string[]
required
Event types to receive, at least one.
["*"] means every type.
ping cannot be listed.string[]
required
1 to 5 addresses Aniva emails when deliveries keep failing.
string
Free text for your own reference, at most 500 characters.
Response
On success, the API returns201 Created with the webhook and its secret.
string
required
The signing secret,
whsec_ plus base64. Aniva shows it only in this response. See Verify the
signature.string
required
Webhook identifier (UUID).
string
required
The HTTPS URL Aniva posts events to.
string
Free text for your own reference. May be
null.string[]
required
Event types this webhook receives.
* means every type.string[]
required
Addresses Aniva emails when deliveries keep failing.
string
required
enabled or disabled.string
ISO 8601 UTC instant the webhook was disabled.
null while enabled.string
Why the webhook was disabled. See Failure notices.
null
while enabled.string
ISO 8601 UTC instant the current failure streak started.
null when the last delivery succeeded.string
ISO 8601 UTC instant the previous secret stops signing.
null when no rotation is in progress.string
required
ISO 8601 UTC instant the webhook was created.
string
required
ISO 8601 UTC instant of the last change.
Error responses
| Status | Description |
|---|---|
400 | Invalid request, for example a bad URL, an unknown event type, invalid alert_emails, or an API key that cannot own a webhook. |
401 | Invalid API key. |
403 | No API key, or an API key without the webhooks_manage scope. |
409 | Your API key already owns 5 webhooks. |
500 | Internal server error. |
curl --request POST \
--url https://anivahealth.com/api/v1/webhooks \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://partner.example.com/webhooks/aniva",
"enabled_events": [
"appointment.confirmed",
"appointment.results.completed",
"home_kit_order.results.completed"
],
"alert_emails": [
"ops@partner.example.com"
],
"description": "Production"
}'
{
"secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw8L0qsE2bkS4=",
"id": "4a6c8e0f-2b4d-4f6a-8c0e-2a4c6e8f0b1d",
"url": "https://partner.example.com/webhooks/aniva",
"description": "Production",
"enabled_events": [
"appointment.confirmed",
"appointment.results.completed",
"home_kit_order.results.completed"
],
"alert_emails": ["ops@partner.example.com"],
"status": "enabled",
"disabled_at": null,
"disabled_reason": null,
"failing_since": null,
"previous_secret_expires_at": null,
"created_at": "2026-10-15T08:00:00.000Z",
"updated_at": "2026-10-15T08:00:00.000Z"
}
{
"error": "url must use https"
}
{
"error": "An API key can own at most 5 webhooks"
}
⌘I
curl --request POST \
--url https://anivahealth.com/api/v1/webhooks \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://partner.example.com/webhooks/aniva",
"enabled_events": [
"appointment.confirmed",
"appointment.results.completed",
"home_kit_order.results.completed"
],
"alert_emails": [
"ops@partner.example.com"
],
"description": "Production"
}'
{
"secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw8L0qsE2bkS4=",
"id": "4a6c8e0f-2b4d-4f6a-8c0e-2a4c6e8f0b1d",
"url": "https://partner.example.com/webhooks/aniva",
"description": "Production",
"enabled_events": [
"appointment.confirmed",
"appointment.results.completed",
"home_kit_order.results.completed"
],
"alert_emails": ["ops@partner.example.com"],
"status": "enabled",
"disabled_at": null,
"disabled_reason": null,
"failing_since": null,
"previous_secret_expires_at": null,
"created_at": "2026-10-15T08:00:00.000Z",
"updated_at": "2026-10-15T08:00:00.000Z"
}
{
"error": "url must use https"
}
{
"error": "An API key can own at most 5 webhooks"
}