Clients
API credentials and their webhook subscriptions.
| Operation | Endpoint |
|---|---|
| Read the webhook endpoint | GET /api/subscriber/{id}/webhook |
| Enable the webhook endpoint | POST /api/subscriber/{id}/webhook/enable |
| Disable the webhook endpoint | POST /api/subscriber/{id}/webhook/disable |
| Send a test event | POST /api/subscriber/{id}/webhook/test |
| Rotate the webhook signing secret | POST /api/subscriber/{id}/webhook/rotate-secret |
| Replace a subscriber's events | POST /api/subscriber/{id}/event |
| List users | GET /api/user |
| Create a user | POST /api/user |
| Get one user | GET /api/user/{id} |
| Update a user | POST /api/user/{id} |
GET /api/subscriber/{id}/webhook
/api/subscriber/{id}/webhookRead the webhook endpoint
The URL, whether it is enabled, failing or disabled (and why), when its current run of failures began, and its newest delivered and failed attempts. Five days of failures with no delivery, or one 410, disable it.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | yes | The subscriber's Signals id or its clientId. |
Responses
| Status | Meaning |
|---|---|
200 | The endpoint. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. Or: A SUBSCRIBER named another subscriber. |
404 | No such subscriber in this tenant. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
subscriberId | string | yes | |
url | string | null | yes | |
status | string | yes | failing: the newest attempts failed; five days of that disables it. disabled: nothing is sent, and new events are held. One of: enabled, failing, disabled. |
disabledAt | date-time | null | yes | Example: "2026-08-27T09:15:00.000Z". |
disabledReason | string | null | yes | gone: it answered 410. failing: five days of failures. manual: disabled by a caller. One of: gone, failing, manual. |
failingSince | date-time | null | yes | When the current run of failures began. Example: "2026-08-27T09:15:00.000Z". |
lastSuccessAt | date-time | null | yes | Example: "2026-08-27T09:15:00.000Z". |
lastFailureAt | date-time | null | yes | Example: "2026-08-27T09:15:00.000Z". |
POST /api/subscriber/{id}/webhook/enable
/api/subscriber/{id}/webhook/enableEnable the webhook endpoint
Resumes deliveries of new events. It re-queues nothing: events held while it was disabled go out only through POST /api/events/redeliver?status=held. Enabling an enabled endpoint changes nothing.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | yes | The subscriber's Signals id or its clientId. |
Responses
| Status | Meaning |
|---|---|
200 | The endpoint as it now stands. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. Or: A SUBSCRIBER named another subscriber. |
404 | No such subscriber in this tenant. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
subscriberId | string | yes | |
url | string | null | yes | |
status | string | yes | failing: the newest attempts failed; five days of that disables it. disabled: nothing is sent, and new events are held. One of: enabled, failing, disabled. |
disabledAt | date-time | null | yes | Example: "2026-08-27T09:15:00.000Z". |
disabledReason | string | null | yes | gone: it answered 410. failing: five days of failures. manual: disabled by a caller. One of: gone, failing, manual. |
failingSince | date-time | null | yes | When the current run of failures began. Example: "2026-08-27T09:15:00.000Z". |
lastSuccessAt | date-time | null | yes | Example: "2026-08-27T09:15:00.000Z". |
lastFailureAt | date-time | null | yes | Example: "2026-08-27T09:15:00.000Z". |
POST /api/subscriber/{id}/webhook/disable
/api/subscriber/{id}/webhook/disableDisable the webhook endpoint
Stops deliveries. Queued events and new ones are held, not dropped, for a redeliver once it is enabled again. Disabling a disabled endpoint keeps its first reason.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | yes | The subscriber's Signals id or its clientId. |
Responses
| Status | Meaning |
|---|---|
200 | The endpoint as it now stands. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. Or: A SUBSCRIBER named another subscriber. |
404 | No such subscriber in this tenant. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
subscriberId | string | yes | |
url | string | null | yes | |
status | string | yes | failing: the newest attempts failed; five days of that disables it. disabled: nothing is sent, and new events are held. One of: enabled, failing, disabled. |
disabledAt | date-time | null | yes | Example: "2026-08-27T09:15:00.000Z". |
disabledReason | string | null | yes | gone: it answered 410. failing: five days of failures. manual: disabled by a caller. One of: gone, failing, manual. |
failingSince | date-time | null | yes | When the current run of failures began. Example: "2026-08-27T09:15:00.000Z". |
lastSuccessAt | date-time | null | yes | Example: "2026-08-27T09:15:00.000Z". |
lastFailureAt | date-time | null | yes | Example: "2026-08-27T09:15:00.000Z". |
POST /api/subscriber/{id}/webhook/test
/api/subscriber/{id}/webhook/testSend a test event
Sends a signed webhook.test event ({ event, subscriber, sentAt }) now, with every header a real delivery carries, and answers what the receiver did. It is not queued, retried or listed, and it works on a disabled endpoint, so a receiver can be checked before it is enabled.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | yes | The subscriber's Signals id or its clientId. |
Responses
| Status | Meaning |
|---|---|
200 | The attempt: whether it was delivered, and the answer. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. Or: A SUBSCRIBER named another subscriber. |
404 | No such subscriber in this tenant. |
422 | The subscriber has no webhookUrl. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
delivered | boolean | yes | |
statusCode | number | null | yes | |
durationMs | number | yes | |
error | string | null | yes | |
responseSnippet | string | null | yes | The first 2 KB of the answer. |
POST /api/subscriber/{id}/webhook/rotate-secret
/api/subscriber/{id}/webhook/rotate-secretRotate the webhook signing secret
Mints a new Standard Webhooks signing secret (whsec_ and 32 random bytes) and returns it this once. Every delivery carries webhook-id and webhook-timestamp; once the subscriber has a secret it also carries webhook-signature, so a receiver verifies with the Standard Webhooks library. The secret it replaces keeps signing until previousSecretExpiresAt (24 h), so webhook-signature holds both and the receiver switches with no gap. Each rotation keeps only the secret it replaces, so rotate again only once the receiver uses the new one. The first call mints the subscriber's first secret. A MANAGER rotates any subscriber of its tenant; a SUBSCRIBER only its own.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | yes | The subscriber's Signals id or its clientId. |
Responses
| Status | Meaning |
|---|---|
200 | The new secret; it cannot be read back later. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. Or: A SUBSCRIBER named another subscriber. |
404 | No such subscriber in this tenant. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
secret | string | yes | The new Standard Webhooks signing secret, whsec_ and 32 random bytes in base64. Example: "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=". |
previousSecretExpiresAt | date-time | null | yes | When the replaced secret stops signing; null when there was none. |
POST /api/subscriber/{id}/event
/api/subscriber/{id}/eventReplace a subscriber's events
The webhook events the subscriber receives, replaced whole.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | yes | The subscriber's Signals id or its clientId. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
events | string[] | yes |
Responses
| Status | Meaning |
|---|---|
200 | { modifiedCount, events }. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. Or: FEATURE_DISABLED: events names an episode event, and the tenant has episodicAlerts off, so it records none. |
404 | No such client in this tenant. |
422 | The payload failed validation, or the client is not a SUBSCRIBER. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
modifiedCount | number | yes | Always 1 on success. |
events | string[] | yes |
GET /api/user
/api/userList users
The tenant's API clients, newest first, in v1's paginate envelope (page, limit defaulting to 10) with nest's nextCursor. role and name filter as in v1.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
limit | query | no | Page size. Defaults to 10, as in v1. |
role | query | no | Only this role: manager, submitter, subscriber (or admin), either case. |
name | query | no | Only clients with exactly this name. |
page | query | no | 1-based, as v1 paged. A page may start at most 10000 rows in; walk further with cursor. |
cursor | query | no | Opaque keyset cursor: a previous answer's nextCursor, passed back verbatim. |
Responses
| Status | Meaning |
|---|---|
200 | One page of users. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. |
422 | A query parameter failed validation, or the page starts too deep. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
totalItems | number | yes | |
limit | number | yes | |
page | number | yes | 1-based. |
totalPages | number | yes | At least 1, even for an empty list. |
pagingCounter | number | yes | The 1-based position of the first item on this page. |
hasPrevPage | boolean | yes | |
hasNextPage | boolean | yes | |
prevPage | number | null | yes | |
nextPage | number | null | yes | |
nextCursor | string | null | yes | Opaque keyset cursor. Pass it back as cursor for the next page; null means this page was the last. Do not construct or parse it. |
items | V1UserSchema[] | yes |
POST /api/user
/api/userCreate a user
Mints an API client. clientId and secret are the Basic credential, chosen by the caller and never returned. role may be v1's lowercase. A SUBSCRIBER needs webhookUrl and at least one event. It is on eventSchema 2 unless the body says 1: on 2 its first Standard Webhooks signing secret is returned this once as signingSecret; on 1 it needs webhookSecret (v1 called it secret). reach is attached (default: the patients attached to it, as v1's) or all (every patient of the tenant, those enrolled later included).
Requires Basic authentication.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
role | string | yes | Validated against the assignable roles rather than the full enum, so this MANAGER-gated route cannot mint a cross-tenant SUPER_ADMIN credential. One of: ADMIN, MANAGER, SUBMITTER, SUBSCRIBER, SUPER_ADMIN, TENANT_PROVISIONER. |
clientId | string | yes | |
secret | string | yes | |
name | string | no | |
webhookUrl | uri | no | |
webhookSecret | string | no | |
events | string[] | no | |
custom | string | no | v1's custom: an opaque string every webhook carries back as x-actimi-custom. |
eventSchema | number | no | 1 keeps v1's event names and bodies; 2, the default, sends one name per state change. One of: 1, 2. |
reach | string | no | attached: the patients attached to it, as v1's; all: every patient of the tenant, later ones included. One of: attached, all. |
Responses
| Status | Meaning |
|---|---|
201 | The user, without its secret; Location names it. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. Or: FEATURE_DISABLED: events names an episode event, and the tenant has episodicAlerts off, so it records none. |
409 | The clientId is taken. |
422 | The payload failed validation. EVENTS_NOT_IN_SCHEMA: events names a type its eventSchema never sends, such as alert.trigger on schema 2. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
tenantId | string | yes | |
clientId | string | yes | |
name | string | null | yes | |
webhookUrl | string | null | yes | Where alert webhooks are POSTed. |
custom | string | no | v1's custom: an opaque string sent back on every webhook in the x-actimi-custom header. Absent when unset. |
hasWebhookSecret | boolean | yes | Whether v1's webhookSecret is set (event schema 1); a schema-2 subscriber signs with its Standard Webhooks secret instead. Never returned: it is write-only. |
events | string[] | yes | Event patterns this client receives, e.g. alert.*. |
eventSchema | number | yes | Which names and bodies its webhooks use. 1: v1's, alert.trigger with refire and resolved flags. 2: one type per state change (alert.triggered, alert.refired, alert.resolved, …) in the Standard Webhooks envelope {type, timestamp, sequence, data}, the alert carrying its version. One of: 1, 2. |
reach | string | yes | A subscriber's patients: attached, those attached to it, as v1's; all, every patient of the tenant, those enrolled later included. One of: attached, all. |
signingSecret | string | no | On a new event-schema-2 subscriber's create answer only: its first Standard Webhooks signing secret, returned this once. Rotate it with POST /api/subscriber/{id}/webhook/rotate-secret. Example: "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=". |
createdAt | date-time | yes | Example: "2026-08-27T09:15:00.000Z". |
updatedAt | date-time | yes | Example: "2026-08-27T09:15:00.000Z". |
_id | string | yes | The same value as id. |
role | string | yes | The role in v1's lowercase. Example: "subscriber". |
tenant | string | yes | The tenant id, under v1's name. |
GET /api/user/{id}
/api/user/{id}Get one user
Without its secret, which is not retrievable.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | yes | The client's Signals id. |
Responses
| Status | Meaning |
|---|---|
200 | The user. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. |
404 | No such client in this tenant. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
tenantId | string | yes | |
clientId | string | yes | |
name | string | null | yes | |
webhookUrl | string | null | yes | Where alert webhooks are POSTed. |
custom | string | no | v1's custom: an opaque string sent back on every webhook in the x-actimi-custom header. Absent when unset. |
hasWebhookSecret | boolean | yes | Whether v1's webhookSecret is set (event schema 1); a schema-2 subscriber signs with its Standard Webhooks secret instead. Never returned: it is write-only. |
events | string[] | yes | Event patterns this client receives, e.g. alert.*. |
eventSchema | number | yes | Which names and bodies its webhooks use. 1: v1's, alert.trigger with refire and resolved flags. 2: one type per state change (alert.triggered, alert.refired, alert.resolved, …) in the Standard Webhooks envelope {type, timestamp, sequence, data}, the alert carrying its version. One of: 1, 2. |
reach | string | yes | A subscriber's patients: attached, those attached to it, as v1's; all, every patient of the tenant, those enrolled later included. One of: attached, all. |
signingSecret | string | no | On a new event-schema-2 subscriber's create answer only: its first Standard Webhooks signing secret, returned this once. Rotate it with POST /api/subscriber/{id}/webhook/rotate-secret. Example: "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=". |
createdAt | date-time | yes | Example: "2026-08-27T09:15:00.000Z". |
updatedAt | date-time | yes | Example: "2026-08-27T09:15:00.000Z". |
_id | string | yes | The same value as id. |
role | string | yes | The role in v1's lowercase. Example: "subscriber". |
tenant | string | yes | The tenant id, under v1's name. |
POST /api/user/{id}
/api/user/{id}Update a user
Sets the name, webhook target, signing secret, events, event schema, reach or credential secret.
Requires Basic authentication.
Parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | yes | The client's Signals id. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
secret | string | no | |
name | string | no | |
webhookUrl | uri | no | |
webhookSecret | string | no | |
events | string[] | no | |
custom | string | no | v1's custom: an opaque string every webhook carries back as x-actimi-custom. |
eventSchema | number | no | Moves the subscriber to another event schema: 2 sends one name per state change. One of: 1, 2. |
reach | string | no | One of: attached, all. |
Responses
| Status | Meaning |
|---|---|
200 | The user as it now stands. |
401 | Missing, malformed or unrecognised Basic credentials. |
403 | Authenticated, but the client's role does not permit this, or it is not attached to the patient. Or: FEATURE_DISABLED: events names an episode event, and the tenant has episodicAlerts off, so it records none. |
404 | No such client in this tenant. |
422 | The payload failed validation. EVENTS_NOT_IN_SCHEMA: the events and eventSchema it would leave never match, such as alert.trigger on schema 2. Change both in one call. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
tenantId | string | yes | |
clientId | string | yes | |
name | string | null | yes | |
webhookUrl | string | null | yes | Where alert webhooks are POSTed. |
custom | string | no | v1's custom: an opaque string sent back on every webhook in the x-actimi-custom header. Absent when unset. |
hasWebhookSecret | boolean | yes | Whether v1's webhookSecret is set (event schema 1); a schema-2 subscriber signs with its Standard Webhooks secret instead. Never returned: it is write-only. |
events | string[] | yes | Event patterns this client receives, e.g. alert.*. |
eventSchema | number | yes | Which names and bodies its webhooks use. 1: v1's, alert.trigger with refire and resolved flags. 2: one type per state change (alert.triggered, alert.refired, alert.resolved, …) in the Standard Webhooks envelope {type, timestamp, sequence, data}, the alert carrying its version. One of: 1, 2. |
reach | string | yes | A subscriber's patients: attached, those attached to it, as v1's; all, every patient of the tenant, those enrolled later included. One of: attached, all. |
signingSecret | string | no | On a new event-schema-2 subscriber's create answer only: its first Standard Webhooks signing secret, returned this once. Rotate it with POST /api/subscriber/{id}/webhook/rotate-secret. Example: "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=". |
createdAt | date-time | yes | Example: "2026-08-27T09:15:00.000Z". |
updatedAt | date-time | yes | Example: "2026-08-27T09:15:00.000Z". |
_id | string | yes | The same value as id. |
role | string | yes | The role in v1's lowercase. Example: "subscriber". |
tenant | string | yes | The tenant id, under v1's name. |
Updated 27 days ago