Skip to Content
APIFailure Alerts

Failure Alerts API

Failure alerts tell your team when a workflow that runs on its own keeps failing. These routes are available to organizations with failure alerts turned on; for any other organization they answer 404.

Authentication

Routes accept a session cookie or an organization API key (Authorization: Bearer $KEEPERHUB_API_KEY). Any member can read. Changing a workflow’s alert settings needs an owner or admin; a key needs the mcp:write scope.

Get Workflow Alert Settings

GET /api/workflows/{workflowId}/failure-alerts

Returns the organization’s rules, the workflow’s own settings (override), the settings in effect, its current failing state, and version, which a change must send back.

While the workflow’s alerts are paused, override carries pausedUntil, pauseUntilSuccess, pauseReason, pausedBy and pausedByAccount; otherwise they are null (pauseUntilSuccess is false).

connections lists the connections shared with the organization that a method can use. unsharedConnections lists your own connections that are not shared, which a method cannot use until they are.

Update Workflow Alert Settings

PUT /api/workflows/{workflowId}/failure-alerts

Request Body

FieldTypeDescription
versionnumberThe version from the last read. A stale one is refused with 409
thresholdnumber | nullFailed runs in a row before an alert, 1 to 20. null follows the organization
timeLimitMinutesnumber | "off" | nullAlso alert after this long failing. null follows the organization
recipientUserIdsstring[] | nullMembers to email. null follows the organization. The list must keep at least one owner or admin who can receive email
customChannelsbooleanUse the workflow’s own channels instead of the organization’s
disableWorkflowbooleanDisable the workflow when it reaches the limit
pausedUntilstring | nullPause alerts until this ISO time, at most 7 days ahead
pauseUntilSuccessbooleanPause until the workflow works again, at most 7 days
pauseReasonstringRequired to pause, extend or change a pause: 3 to 200 characters

Sending the pause fields unchanged keeps the pause as it is. Sending neither pausedUntil nor pauseUntilSuccess resumes. The response is the same as the GET, plus pauseChange: paused, changed, resumed, or null when the pause did not change.

Every pause, change to a pause and resume is announced: the people the workflow’s alerts reached before the change, and every owner, get a notice by email and on the workflow’s chat methods, and it is listed in the organization’s sent alerts. People taken off a recipient list are told the same way. A workflow’s pause can change at most 6 times an hour; more is refused with 429.

Get Organization Alert Settings

GET /api/organizations/{organizationId}/failure-alerts

Returns the organization’s rules, who gets email, its methods (with each one’s health), the connections methods can use, any pause, every workflow with its own rules or paused alerts, and version, which a change can send back so it is refused if someone else saved first.

Update Organization Alert Settings

PUT /api/organizations/{organizationId}/failure-alerts

Needs an owner or admin.

Request Body

FieldTypeDescription
versionnumberOptional. The version from the last read; a stale one is refused with 409
thresholdnumberFailed runs in a row before an alert, 1 to 20
timeLimitMinutesnumber | nullAlso alert after this long failing: 60, 360 or 1440; null or 0 for no time limit
remindDailybooleanRemind once a day while a workflow keeps failing. Leave it out to keep it as it is (on by default)
notifyRecoverybooleanTell people when a workflow works again. Leave it out to keep it as it is (on by default)
recipientUserIdsstring[]Members to email. Must include at least one owner or admin who can receive email
channelsobject[]Optional. The full list of chat and PagerDuty methods, up to 20; leave it out to keep them as they are

Each item in channels has integrationId (a connection shared with the organization), destination (chat ID, channel or PagerDuty service, depending on the connection) and role ("always" or "backup"); send id to keep an existing method. Each new or changed method is checked before it is saved; one that cannot receive alerts is refused with 400.

Pause Organization Alerts

PUT /api/organizations/{organizationId}/failure-alerts/pause DELETE /api/organizations/{organizationId}/failure-alerts/pause

Needs an owner or admin. PUT pauses every alert of the organization until until (an ISO time, at most 7 days from when the pause started), with an optional reason. DELETE resumes at once. Workflows keep running while alerts are paused. Each pause, change and resume is announced to everyone who gets alerts, and at most 5 can happen in an hour; more is refused with 429.

Send a Test

POST /api/organizations/{organizationId}/failure-alerts/test

Needs an owner or admin. Sends one test message and reports whether it was delivered.

FieldTypeDescription
channelstringemail, slack, discord, telegram or pagerduty
tostringEmail only: "me" (default) or "recipients"
recipientUserIdsstring[]Email only, with to: "recipients": who to email
integrationIdstringChat and PagerDuty: the connection to test
destinationstringChat and PagerDuty: where to send it
channelIdstringOptional: a saved method; a passing test turns a method that stopped working back on
pagerDutyModestringPagerDuty only: "change" (default, no page) or "page"

Tests are rate limited; too many are refused with 429.

Preview a Message

GET /api/organizations/{organizationId}/failure-alerts/preview?sample=alert

Returns a sample message as each method would show it. sample is alert (default), missed, disabled or recovery.

All PUT and POST bodies must be a JSON object; anything else is refused with 400.

List Sent Alerts

GET /api/organizations/{organizationId}/failure-alerts/history

Every alert, reminder, recovery and notice sent to the organization, newest first.

Query Parameters

ParameterTypeDescription
pagenumberA numbered page from 1 to 100000, with total and pages in the response
cursorstringThe nextCursor of the previous response, in place of page
limitnumberRows per page, at most 500
workflowstringA workflow’s exact id, or part of its current name, so alerts sent before a rename still match. At most 200 characters
workflowIdstringOne workflow’s exact id
kindstringOne message kind, such as alert, reminder, recovery, workflow_alerts_paused, workflow_alerts_resumed, workflow_alerts_pause_ended or recipients_removed
scopestringalerts: alerts, reminders, recoveries and notices about silencing, without the organization-wide pause notices or tests. people: what people did: pauses and resumes (of one workflow or the whole organization), removals from alerts and tests
resultstringdelivered, failed, waiting or withdrawn
channelstringemail, slack, discord, telegram or pagerduty
bystringWho caused it: a person’s name, or KeeperHub
tostringPart of the address or channel it went to
sincestring24h, 7d or 30d
formatstringcsv returns up to 500 rows as a CSV file