Knock


Schemes	`knock://`
Cargo feature	`service-knock`
Service	https://knock.app/
Body formats	`text`, `html`, `markdown` (first is the default)
Attachments	no
Title length	250 characters
Body length	32,768 characters
Body lines	unlimited
Request throttle	none
Vendor URLs accepted	no

URL formats

knock://{api_key}/{workflow_key}/{targets}

URL tokens

Token	Meaning	Type	Required	Notes
`{api_key}`	API Key	string	yes	secret
`{targets}`	Recipients	list	yes	separated by `/`; user id, e-mail or `+phone`
`{workflow_key}`	Workflow Key	string	yes

Query parameters

Parameter	Meaning	Type	Default	Notes
`actor`	Actor	string
`cancel`	Cancellation Key	string
`host`	API Host	string	`api.knock.app`	`host[:port][/path]` or a full `http(s)://` URL
`tenant`	Tenant	string
`to`	Recipients	list		sets `{targets}`

Prefixed parameters:

:name=value: Workflow Data
+name=value: HTTP Header

The common URL parameters (format, overflow, verify, redirect, cto, rto, retry, wait, store, tag, tz, user, password, port, optional, emojis) apply as well.

Examples

Accepted URLs (tokens are fake):

knock://sk_test_123/alerts/u1/u1
knock://sk_test_123/new-comment/dr_grant
knock://sk_test_123/new-comment/dr_grant/ellie@example.com/+15551234567
knock://sk_test_123/alerts?to=u1,u2&host=knock.example.com&+X-Env=staging
knock://sk_test_123/new-comment/dr_grant?actor=mr_dna&tenant=ingen&cancel=incident_1993&:severity=high

Rejected URLs:

knock://
knock://sk_test_123
knock://sk_test_123/new-comment
knock://sk_test_123/new-comment/u1?host=bad_host!

Send one from the command line:

mercurio -t 'Backup' -b 'Finished in 42s' 'knock://sk_test_123/alerts/u1/u1'

Notes

Knock (knock://): triggers a Knock workflow for the recipients, written from the API reference (https://docs.knock.app/api-reference/workflows/trigger).

knock://{api_key}/{workflow_key}/{recipient}[/{recipient}...]

Options:

?host=api.example.com[:port][/path] (or a full http(s):// URL) overrides the API base (default https://api.knock.app).
?to=a,b adds recipients; ?actor=.., ?tenant=.. and ?cancel=.. (cancellation_key) are passed through.
:key=value adds key to the workflow data; +Header=value adds an HTTP header.

Each recipient is a user id, an e-mail (inline identification {"id": email, "email": email}) or +<phone> ({"id": phone, "phone_number": phone}). One POST /v1/workflows/{key}/trigger is sent per 1000 recipients with Authorization: Bearer {api_key} and {"recipients": [...], "data": {"title", "body", "type"}}; any 2xx is success.

Differences with Apprise

Not in Apprise; written from the vendor documentation (hand-written fixtures).

Keyboard shortcuts