Clients

API credentials and their webhook subscriptions.

OperationEndpoint
Read the webhook endpointGET /api/subscriber/{id}/webhook
Enable the webhook endpointPOST /api/subscriber/{id}/webhook/enable
Disable the webhook endpointPOST /api/subscriber/{id}/webhook/disable
Send a test eventPOST /api/subscriber/{id}/webhook/test
Rotate the webhook signing secretPOST /api/subscriber/{id}/webhook/rotate-secret
Replace a subscriber's eventsPOST /api/subscriber/{id}/event
List usersGET /api/user
Create a userPOST /api/user
Get one userGET /api/user/{id}
Update a userPOST /api/user/{id}

GET /api/subscriber/{id}/webhook

Read 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

NameInRequiredDescription
idpathyesThe subscriber's Signals id or its clientId.

Responses

StatusMeaning
200The endpoint.
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, but the client's role does not permit this, or it is not attached to the patient. Or: A SUBSCRIBER named another subscriber.
404No such subscriber in this tenant.

Response body

FieldTypeRequiredDescription
subscriberIdstringyes
urlstring | nullyes
statusstringyesfailing: the newest attempts failed; five days of that disables it. disabled: nothing is sent, and new events are held. One of: enabled, failing, disabled.
disabledAtdate-time | nullyesExample: "2026-08-27T09:15:00.000Z".
disabledReasonstring | nullyesgone: it answered 410. failing: five days of failures. manual: disabled by a caller. One of: gone, failing, manual.
failingSincedate-time | nullyesWhen the current run of failures began. Example: "2026-08-27T09:15:00.000Z".
lastSuccessAtdate-time | nullyesExample: "2026-08-27T09:15:00.000Z".
lastFailureAtdate-time | nullyesExample: "2026-08-27T09:15:00.000Z".

POST /api/subscriber/{id}/webhook/enable

Enable 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

NameInRequiredDescription
idpathyesThe subscriber's Signals id or its clientId.

Responses

StatusMeaning
200The endpoint as it now stands.
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, but the client's role does not permit this, or it is not attached to the patient. Or: A SUBSCRIBER named another subscriber.
404No such subscriber in this tenant.

Response body

FieldTypeRequiredDescription
subscriberIdstringyes
urlstring | nullyes
statusstringyesfailing: the newest attempts failed; five days of that disables it. disabled: nothing is sent, and new events are held. One of: enabled, failing, disabled.
disabledAtdate-time | nullyesExample: "2026-08-27T09:15:00.000Z".
disabledReasonstring | nullyesgone: it answered 410. failing: five days of failures. manual: disabled by a caller. One of: gone, failing, manual.
failingSincedate-time | nullyesWhen the current run of failures began. Example: "2026-08-27T09:15:00.000Z".
lastSuccessAtdate-time | nullyesExample: "2026-08-27T09:15:00.000Z".
lastFailureAtdate-time | nullyesExample: "2026-08-27T09:15:00.000Z".

POST /api/subscriber/{id}/webhook/disable

Disable 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

NameInRequiredDescription
idpathyesThe subscriber's Signals id or its clientId.

Responses

StatusMeaning
200The endpoint as it now stands.
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, but the client's role does not permit this, or it is not attached to the patient. Or: A SUBSCRIBER named another subscriber.
404No such subscriber in this tenant.

Response body

FieldTypeRequiredDescription
subscriberIdstringyes
urlstring | nullyes
statusstringyesfailing: the newest attempts failed; five days of that disables it. disabled: nothing is sent, and new events are held. One of: enabled, failing, disabled.
disabledAtdate-time | nullyesExample: "2026-08-27T09:15:00.000Z".
disabledReasonstring | nullyesgone: it answered 410. failing: five days of failures. manual: disabled by a caller. One of: gone, failing, manual.
failingSincedate-time | nullyesWhen the current run of failures began. Example: "2026-08-27T09:15:00.000Z".
lastSuccessAtdate-time | nullyesExample: "2026-08-27T09:15:00.000Z".
lastFailureAtdate-time | nullyesExample: "2026-08-27T09:15:00.000Z".

POST /api/subscriber/{id}/webhook/test

Send 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

NameInRequiredDescription
idpathyesThe subscriber's Signals id or its clientId.

Responses

StatusMeaning
200The attempt: whether it was delivered, and the answer.
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, but the client's role does not permit this, or it is not attached to the patient. Or: A SUBSCRIBER named another subscriber.
404No such subscriber in this tenant.
422The subscriber has no webhookUrl.

Response body

FieldTypeRequiredDescription
deliveredbooleanyes
statusCodenumber | nullyes
durationMsnumberyes
errorstring | nullyes
responseSnippetstring | nullyesThe first 2 KB of the answer.

POST /api/subscriber/{id}/webhook/rotate-secret

Rotate 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

NameInRequiredDescription
idpathyesThe subscriber's Signals id or its clientId.

Responses

StatusMeaning
200The new secret; it cannot be read back later.
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, but the client's role does not permit this, or it is not attached to the patient. Or: A SUBSCRIBER named another subscriber.
404No such subscriber in this tenant.

Response body

FieldTypeRequiredDescription
secretstringyesThe new Standard Webhooks signing secret, whsec_ and 32 random bytes in base64. Example: "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=".
previousSecretExpiresAtdate-time | nullyesWhen the replaced secret stops signing; null when there was none.

POST /api/subscriber/{id}/event

Replace a subscriber's events

The webhook events the subscriber receives, replaced whole.

Requires Basic authentication.

Parameters

NameInRequiredDescription
idpathyesThe subscriber's Signals id or its clientId.

Request body

FieldTypeRequiredDescription
eventsstring[]yes

Responses

StatusMeaning
200{ modifiedCount, events }.
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, 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.
404No such client in this tenant.
422The payload failed validation, or the client is not a SUBSCRIBER.

Response body

FieldTypeRequiredDescription
modifiedCountnumberyesAlways 1 on success.
eventsstring[]yes

GET /api/user

List 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

NameInRequiredDescription
limitquerynoPage size. Defaults to 10, as in v1.
rolequerynoOnly this role: manager, submitter, subscriber (or admin), either case.
namequerynoOnly clients with exactly this name.
pagequeryno1-based, as v1 paged. A page may start at most 10000 rows in; walk further with cursor.
cursorquerynoOpaque keyset cursor: a previous answer's nextCursor, passed back verbatim.

Responses

StatusMeaning
200One page of users.
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, but the client's role does not permit this, or it is not attached to the patient.
422A query parameter failed validation, or the page starts too deep.

Response body

FieldTypeRequiredDescription
totalItemsnumberyes
limitnumberyes
pagenumberyes1-based.
totalPagesnumberyesAt least 1, even for an empty list.
pagingCounternumberyesThe 1-based position of the first item on this page.
hasPrevPagebooleanyes
hasNextPagebooleanyes
prevPagenumber | nullyes
nextPagenumber | nullyes
nextCursorstring | nullyesOpaque keyset cursor. Pass it back as cursor for the next page; null means this page was the last. Do not construct or parse it.
itemsV1UserSchema[]yes

POST /api/user

Create 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

FieldTypeRequiredDescription
rolestringyesValidated 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.
clientIdstringyes
secretstringyes
namestringno
webhookUrlurino
webhookSecretstringno
eventsstring[]no
customstringnov1's custom: an opaque string every webhook carries back as x-actimi-custom.
eventSchemanumberno1 keeps v1's event names and bodies; 2, the default, sends one name per state change. One of: 1, 2.
reachstringnoattached: the patients attached to it, as v1's; all: every patient of the tenant, later ones included. One of: attached, all.

Responses

StatusMeaning
201The user, without its secret; Location names it.
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, 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.
409The clientId is taken.
422The payload failed validation. EVENTS_NOT_IN_SCHEMA: events names a type its eventSchema never sends, such as alert.trigger on schema 2.

Response body

FieldTypeRequiredDescription
idstringyes
tenantIdstringyes
clientIdstringyes
namestring | nullyes
webhookUrlstring | nullyesWhere alert webhooks are POSTed.
customstringnov1's custom: an opaque string sent back on every webhook in the x-actimi-custom header. Absent when unset.
hasWebhookSecretbooleanyesWhether 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.
eventsstring[]yesEvent patterns this client receives, e.g. alert.*.
eventSchemanumberyesWhich 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.
reachstringyesA 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.
signingSecretstringnoOn 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=".
createdAtdate-timeyesExample: "2026-08-27T09:15:00.000Z".
updatedAtdate-timeyesExample: "2026-08-27T09:15:00.000Z".
_idstringyesThe same value as id.
rolestringyesThe role in v1's lowercase. Example: "subscriber".
tenantstringyesThe tenant id, under v1's name.

GET /api/user/{id}

Get one user

Without its secret, which is not retrievable.

Requires Basic authentication.

Parameters

NameInRequiredDescription
idpathyesThe client's Signals id.

Responses

StatusMeaning
200The user.
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, but the client's role does not permit this, or it is not attached to the patient.
404No such client in this tenant.

Response body

FieldTypeRequiredDescription
idstringyes
tenantIdstringyes
clientIdstringyes
namestring | nullyes
webhookUrlstring | nullyesWhere alert webhooks are POSTed.
customstringnov1's custom: an opaque string sent back on every webhook in the x-actimi-custom header. Absent when unset.
hasWebhookSecretbooleanyesWhether 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.
eventsstring[]yesEvent patterns this client receives, e.g. alert.*.
eventSchemanumberyesWhich 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.
reachstringyesA 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.
signingSecretstringnoOn 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=".
createdAtdate-timeyesExample: "2026-08-27T09:15:00.000Z".
updatedAtdate-timeyesExample: "2026-08-27T09:15:00.000Z".
_idstringyesThe same value as id.
rolestringyesThe role in v1's lowercase. Example: "subscriber".
tenantstringyesThe tenant id, under v1's name.

POST /api/user/{id}

Update a user

Sets the name, webhook target, signing secret, events, event schema, reach or credential secret.

Requires Basic authentication.

Parameters

NameInRequiredDescription
idpathyesThe client's Signals id.

Request body

FieldTypeRequiredDescription
secretstringno
namestringno
webhookUrlurino
webhookSecretstringno
eventsstring[]no
customstringnov1's custom: an opaque string every webhook carries back as x-actimi-custom.
eventSchemanumbernoMoves the subscriber to another event schema: 2 sends one name per state change. One of: 1, 2.
reachstringnoOne of: attached, all.

Responses

StatusMeaning
200The user as it now stands.
401Missing, malformed or unrecognised Basic credentials.
403Authenticated, 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.
404No such client in this tenant.
422The 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

FieldTypeRequiredDescription
idstringyes
tenantIdstringyes
clientIdstringyes
namestring | nullyes
webhookUrlstring | nullyesWhere alert webhooks are POSTed.
customstringnov1's custom: an opaque string sent back on every webhook in the x-actimi-custom header. Absent when unset.
hasWebhookSecretbooleanyesWhether 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.
eventsstring[]yesEvent patterns this client receives, e.g. alert.*.
eventSchemanumberyesWhich 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.
reachstringyesA 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.
signingSecretstringnoOn 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=".
createdAtdate-timeyesExample: "2026-08-27T09:15:00.000Z".
updatedAtdate-timeyesExample: "2026-08-27T09:15:00.000Z".
_idstringyesThe same value as id.
rolestringyesThe role in v1's lowercase. Example: "subscriber".
tenantstringyesThe tenant id, under v1's name.

Did this page help you?