Webhooks

Webhooks push reports out of PulseDeck. Every time a report arrives that matches a webhook’s filters, PulseDeck POSTs it to your endpoint — a Slack channel, a Discord server, a Mattermost instance, or your own API. Delivery is asynchronous, retried on failure, and logged.

Manage them under Settings → Webhooks.

Creating a webhook

Click Add webhook and fill the form:

Field	What it does
Name	A human label, e.g. Critical → #alerts.
Endpoint URL	Where the POST goes. Validated for safety on save (see URL safety).
Format	generic, slack, discord, or mattermost. See Formats.
Severities	Which severities fire it — info warning critical . Empty = all.
Categories	Which categories fire it. Empty = all.
Enabled	Toggle to pause without deleting.

For the generic format, a signing secret is shown once on create with a copy button. Store it now — it’s never displayed again (see Signing).

What fires a webhook

A new report fires a webhook when it matches both filters:

(severities is empty OR report.severity ∈ severities)
AND
(categories is empty OR report.category ∈ categories)

Empty means all, not none

An empty severity or category list matches everything, not nothing. A webhook with severities [critical] and no categories fires for every critical report in the workspace. To narrow it, add to the lists.

Formats

Format	Payload	Signed	Use for
generic	Versioned JSON envelope: workspace, category, stream, and report objects.	✓	Your own API, custom integrations.
slack	Slack message blocks, severity-colored, with a link back to the report.		Slack channels (incoming webhook URL).
discord	Discord embeds with fields, color-mapped by severity.		Discord channels (webhook URL).
mattermost	Slack-compatible payload.		Mattermost instances.

For Slack, Discord, and Mattermost, paste the channel’s incoming-webhook URL as the endpoint — PulseDeck formats the message to match. Only generic is signed; the vendor formats don’t use a secret.

Signing

The generic format signs every request with an HMAC-SHA256 header derived from the webhook’s secret, so your endpoint can verify the payload came from PulseDeck and wasn’t tampered with. Compute the HMAC of the raw request body with your stored secret and compare it to the header.

• The secret is shown only on create and on rotate.
• To roll it, open the webhook’s menu → Rotate signing secret. The new secret is shown once; the old one stops validating immediately.
• Slack/Discord/Mattermost webhooks have no secret — signing and rotation are hidden for them.

Testing before you rely on it

From a webhook’s menu, Send test enqueues a synthetic report with placeholder data to your endpoint. Use it to confirm the URL, format, and (for Slack/Discord) channel routing work before pointing real alerts at it.

Delivery, retries & the log

Delivery is asynchronous — a webhook is queued after the report is ingested, not sent inline, so it never slows report ingestion.

• A 2xx response marks the delivery succeeded.
• A non-2xx response or a timeout (10s) marks it failed and retries with exponential backoff, up to 5 attempts, before giving up.
• Every attempt is recorded with its HTTP status, any error, and a timestamp.

Open a webhook’s menu → Delivery log for a full-page history, newest first. Each terminal delivery (succeeded or failed) has a Redeliver action that re-enqueues it — handy after you fix an endpoint outage.

The log outlives the report

The payload is frozen when the delivery is enqueued and the log row is durable. Even if the original report is later purged by retention, its delivery record and formatted payload remain for audit.

URL safety

Endpoint URLs are checked on create and update. In the hosted product, requests to private and loopback addresses (127.0.0.1, 10.x.x.x, 169.254.169.254, …) are blocked to prevent server-side request forgery. Self-hosters who need to reach an internal endpoint can allow private addresses in configuration — see Self-hosting.

Editing & deleting

Click a webhook row to edit any field — name, URL, format, filters, or enabled state. Deleting a webhook removes it and its entire delivery history; there’s no undo. To stop a webhook temporarily, toggle Enabled off instead.

Who can manage webhooks

Webhooks live in workspace settings; managing them follows the same bar as other settings — admin role or higher. See Members & roles.

Next steps

• Categories & streams — the structure webhook filters target.
• Sending reports — where the reports that fire webhooks come from.