Skip to main content

Webhooks

Abyss Monitor webhooks notify an external URL whenever an application event or a Sentinel check occurs. They are the recommended way to wire Monitor to an external system (Slack, alert dispatcher, internal automation, etc.).

Scopes​

A webhook declares one or several scopes:

EVENT​

Triggered when an application event is received. You can filter the listened events by:

  • equals — exact match (e.g. auth.user.signup),
  • startsWith — prefix (e.g. auth.),
  • endsWith — suffix (e.g. .error),
  • include — substring.

Filters are cumulative: an event passes if it matches at least one rule.

SENTINEL​

Triggered on each Sentinel check. Available filters:

  • type — restrict to one or several types (PING, HTTP, TCP),
  • notifyOnSuccess — notify on success,
  • notifyOnFailure — notify on failure.

Create a webhook​

  1. Open the Application in Abyss Monitor and go to the Webhooks tab.
  2. Click Create.
  3. Fill in:
    • Name and description,
    • Target URL (HTTPS recommended),
    • Scopes (EVENT, SENTINEL, or both) and their filters,
    • Enabled / disabled state.
  4. Confirm. A signing secret is generated: keep it, you'll need it to validate payloads on your end.

Signature and validation​

Every outgoing call includes a HMAC SHA-256 signature of the body, computed with the webhook secret. The header is abyss-monitor-webhook-signature.

On your side, recompute the same signature from the raw body and the secret, then compare:

import crypto from 'crypto';

const signature = req.headers['abyss-monitor-webhook-signature'];
const expected = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(JSON.stringify(req.body))
  .digest('hex');

if (signature !== expected) {
  throw new Error('Invalid signature');
}

If you suspect the secret has been leaked, you can regenerate it from the webhook page. The previous secret is invalidated immediately.

Delivery history​

Every trigger creates an entry in the webhook history, which keeps:

  • the event or check that triggered the send,
  • the HTTP response code returned by your server,
  • the call duration,
  • the body sent and the response received.

Retry and failures​

If your server returns an error (5xx, timeout), Abyss Monitor automatically retries with an increasing delay between attempts. Once retries are exhausted, the delivery is marked as failed and remains visible in the history.

To avoid missing events, respond with a 2xx code as soon as you've received and persisted the data. Business processing can be asynchronous on your side.

Manage existing webhooks​

From the Webhooks tab you can:

  • edit a webhook (URL, filters, enabled / disabled state),
  • inspect delivery history,
  • regenerate the signing secret,
  • delete a webhook.