Channels, escalation, webhooks and email

Shared alert channels, acknowledge rules, escalation steps, signed webhooks and email delivery, set up in the console.

A channel is a group inside a team that receives one kind of alert. Everything you can send to yourself you can send to a channel.

Create a channel#

An admin creates a channel with one request. Choose its acknowledge rule and its members, or set everyone, which puts every current member on it and each future joiner too (the web console toggles it).

curl -X POST https://nowlark.com/v1/teams/team_…/channels \
  -H "Authorization: Bearer nla_…" -H "Content-Type: application/json" \
  -d '{"name":"oncall","ack_policy":"any","members":"all"}'

Send to a channel#

A channel key is a key that can send to one channel and nothing else, so a script on a server cannot touch anything else.

curl https://nowlark.com/v1/notify \
  -H "X-Nowlark-Key: nlk_…" -H "Content-Type: application/json" \
  -d '{"source":"Checkout","title":"Payments failing","priority":2}'

• On a member's phone the source reads <Team name> / <source>, so team senders are muted and coloured apart from their own.
• Scheduling, recurring sends, expiry, tags and device filters all work. A question sent to a channel is settled by the first member to answer.
• Images and buttons are decided by the owner's pass, not each member's. A member on a free account receives them.
• Read the receipt for who has opened it, by the names they chose for the team.
• A channel key stops working the moment the person who made it leaves the team, is demoted below sender, or leaves the channel.

Escalation#

If nobody opens the alert, tell the next group. Set it with PUT /v1/channels/{id}/escalation and a list of steps, each naming who and how many seconds in.

• Whether to escalate is read at the moment a step is due. If anyone has opened it, by any route, the step is skipped. Nothing has to cancel it.
• A person who left the channel in the meantime is not paged.
• Editing the plan does not change an alert already in flight.
• It works on scheduled and recurring sends too.
• Repeat the steps once, twice or three times until someone opens it ("repeat": 2, "repeat_after": 900 repeats twice, 15 minutes after the last step each time). The steps start again from step 1. People who already have the alert are pinged again on that same alert, not sent a second one.

Beyond the phone: webhooks and email#

A channel always reaches its members' phones. A destination adds somewhere else, up to ten per channel.

Add one with POST /v1/channels/{id}/destinations and a kind of webhook or email.

Events a destination can follow: an alert arrived, someone opened it (or a form message was claimed), and a later step was notified. Pick any of them.

Webhooks carry the team, channel, source, title, body, link, priority and, once opened, who opened it by their team name. Every delivery is signed with a secret shown once (X-Nowlark-Signature), carries a delivery id for deduplicating, and is retried after 30 seconds, 5 minutes, 30 minutes, 2 hours and 12 hours. A destination that fails 20 times in a row is switched off with the reason, and you switch it back on after fixing it. Send a test event (…/destinations/{id}/test) to check your receiver.

Email is for the people who will not install an app. Nothing is sent to an address until its owner clicks a link confirming it. Every email carries a one-click unsubscribe, and an address that unsubscribes or bounces for good is remembered and not emailed again from any channel. An address receives at most 60 emails an hour; anything over waits and is sent later, not lost.

Remove people and clean up#

Take someone off a channel and their copies of its alerts go with them. Deleting a channel deletes its keys and every member's copies.

Next: team forms that page your team.