Integrations: webhooks, Slack and Discord

On Pro and Team, the Integrations page (Account → Integrations) sends what happens in your node groups beside the alert mail: alerts to a Slack or Discord channel, and alerts or every timeline event to a webhook of yours. An organisation has up to five integrations, each a webhook, a Slack channel or a Discord channel. The alert mail still reaches every member on every plan; integrations come in addition. On another plan the page explains the plan, and integrations added on Pro stay and send again once the plan includes them.

How do I add a Slack channel?

1. On api.slack.com/apps, Create New App → From scratch: name the app and pick the workspace.
2. Open Incoming Webhooks and turn Activate Incoming Webhooks on.
3. Add New Webhook to Workspace, pick the channel and Authorize.
4. On the Integrations page, Add integration of the kind Slack. Paste the https://hooks.slack.com/services/… URL, and choose the Lowest level (Notice, Warning or Critical) and the Language of the messages (English, Turkish, German, Spanish or French, the panel’s languages).

How do I add a Discord channel?

In Discord, Server Settings → Integrations → Webhooks → New Webhook, pick the channel, then Copy Webhook URL (https://discord.com/api/webhooks/…). Add it on the Integrations page as for Slack, with the kind Discord, a lowest level and a language.

What does a channel receive?

One message per alert batch, the same batch as the alert mail, which gathers alerts for two minutes. The message holds the batch’s alerts at or above the channel’s level, with the mail’s lines, group by group, and a link to each group’s timeline.

Discord gets the same messages, and they never mention anyone. A batch longer than Discord’s 2,000 characters is cut and says how many more alerts the timeline holds.

A Slack or Discord URL works like a password: Hetscale keeps it sealed and shows only its host and its last four characters.

How does a webhook work?

A webhook sends to an https URL of yours with public addresses, under the same rules as the webhook adapter. It takes Alerts, Every event or both:

• Alerts: every alert your members are mailed, each the moment it is raised, never batched.
• Every event: every event of your node groups’ timelines: scaling, servers, healing, settings.

The signing secret is shown once, after you add the webhook. Verify each delivery exactly as for the webhook adapter: How do I verify a delivery?. New signing secret makes a new one, and the old one keeps signing beside it for a day.

Each body is JSON with event, delivery_id and sent_at; organization; group and node, each null when the delivery has none; text, the delivery in words; and url, a link to the group’s timeline. The webhooks reference lists the timeline, alert and ping deliveries field by field. Within /v1 the bodies only gain fields.

How do I test an integration?

Send a test sends a test message: to a Slack or Discord channel in its language, and to a webhook a ping event, signed like every delivery. Its result is in the delivery log.

How do I change an integration?

Edit in the integration’s row menu changes its name, its address within its kind (a Slack URL stays a Slack one), a webhook’s choice of Alerts and Every event, at least one, and a channel’s Lowest level and Language. The kind does not change, and neither does the signing secret, which only New signing secret replaces.

A new address keeps the webhook’s signing secret and the delivery log. A channel’s URL is never shown again, so its field starts empty, and an empty field keeps the URL. A new level, language or choice applies from the next delivery. Nothing is sent to a new address until you ask: the saved notice offers a test, and a test that arrives also resumes a suspended integration. Each change is in the audit log.

What happens when deliveries fail?

A failed delivery is retried with backoff: eight attempts over about 38 minutes, as for the webhook adapter’s events. An integration whose deliveries all fail for 30 minutes is suspended:

• what was waiting is abandoned, and your members get an alert by mail, and on your other integrations;
• while it is suspended, it takes one delivery an hour as a probe; the deliveries that arrive meanwhile are dropped, and the page counts them;
• a successful probe, a successful Send a test or Resume brings it back at once.

Where do I see the deliveries?

Each integration’s Deliveries list what it was sent in the last 30 days, the newest first, with the state of each delivery, its attempts and the last answer.