Skip to content
Browse docs
Docs / Alerts and channels / Webhooks

Webhooks

Send each alert as a signed JSON POST to your own endpoint, to feed a database, an internal tool, Zapier, Make or n8n. You can also receive every check, not just alerts.

Add a webhook to a task

  1. Paste your endpoint

    Edit the task, go to its Channels tab, switch on Webhook and paste the URL into the row. Click Send test: the row says “Sent to” your endpoint and the status code it answered, or why it failed, such as “The webhook answered 405”. Click Add a webhook for another endpoint, up to 5 per task.

    The Webhook card with an endpoint in its row, Send test, Add a webhook and the Send every check switch
  2. Choose what to send

    Leave Send every check (data feed) off to receive alerts only. Switch it on to receive every completed check, which is useful for tracking a value such as a price over time.

  3. Save

    Click Update task.

The request

monity.ai sends POST with Content-Type: application/json and User-Agent: Monity-Bot/1.0. The body includes:

Field Content
taskId, taskName The task
websiteUrl The monitored page
status The check’s result
aiSummary What changed, in plain words
checkUrl The check in monity.ai
imageUrl, prevImage, imageDiffUrl Current and previous screenshots, and the highlighted difference
output The values the task pulls out of the page, if its Notify me when rule asks for them
checkDate, notificationTimestamp When the check ran and when the webhook was sent
payloadVersion 2, plus extra context such as labels, compareType, percentDifference and trigger

A test delivery has the same shape, with test: true and the trigger SAMPLE, so your endpoint can tell it from a real alert.

Failed deliveries are retried twice, after about 1 and 3 seconds, when the endpoint times out, returns a 5xx error or answers 429. Other 4xx responses are not retried. Each attempt waits up to 15 seconds.

Verify the signature

Every delivery carries X-Monity-Timestamp and X-Monity-Signature. The signature is sha256= followed by the hex HMAC-SHA256 of the timestamp, a dot and the raw request body, keyed with your signing secret. Find the secret in Integrations (left sidebar): on the Webhook signing card, click Signing secret, then Reveal signing secret.

The Webhook signing side sheet in Integrations, with the two headers each delivery carries and the Reveal signing secret button
import crypto from 'node:crypto';

function isFromMonity(rawBody, headers, secret) {
  const timestamp = headers['x-monity-timestamp'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  const given = headers['x-monity-signature'] || '';
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

Compute the signature over the body exactly as received, before parsing it. To reject replayed requests, also check that the timestamp (milliseconds since 1970) is recent.

Kamil, Alex and Martyna Median reply under 6 hours

Have a question?

Pricing, security, or scoping - pick a route and you will land in a real person's inbox.