Alert webhooks

A webhook notification destination sends every alert event to a URL you own. This page is the contract your endpoint can rely on.

The request

Maple sends a POST with a JSON body and these headers:

Respond with any 2xx within 15 seconds. The response body is ignored.

Events

Payload

{
	"eventType": "trigger",
	"incidentId": "b6f1…",
	"incidentStatus": "open",
	"dedupeKey": "org_…:alrt_…:checkout",
	"rule": {
		"id": "alrt_…",
		"name": "Checkout error rate",
		"signalType": "error_rate",
		"severity": "critical",
		"groupKey": "checkout",
		"comparator": "gt",
		"threshold": 5,
		"thresholdUpper": null,
		"windowMinutes": 5
	},
	"observed": { "value": 8.4, "sampleCount": 1250 },
	"template": null,
	"chart": { "url": "https://…" },
	"linkUrl": "https://app.maple.dev/alerts/…",
	"chatUrl": "https://app.maple.dev/chat?…",
	"sentAt": "2026-09-25T09:14:00.000Z",
	"event": { "specversion": "1.0", "type": "dev.maple.alert.lifecycle.trigger.v1", "…": "…" }
}

The body is identical for every destination’s webhook, regardless of the rule’s notification template. Treat unknown fields as additive: new fields can appear without notice.

Error issue notifications

A destination listed in your organization’s error notification policy (set with the update_error_notification_policy MCP tool or the API) also receives error issue events: a new issue, a regression, a resolve, and optionally workflow changes and claims. They carry the same headers and a smaller body: eventType, incidentId, incidentStatus, dedupeKey, rule, observed, linkUrl, chatUrl and sentAt, without event, template or chart. Here rule.id is the issue ID, rule.name reads <ExceptionType> in <service>, and observed.value is the occurrence count. dedupeKey starts with error:.

Issues escalated by triage arrive with eventType: "escalation" in the body and an extra escalation object describing the issue. The x-maple-event-type header on these reads trigger, so branch on the body’s eventType.

Verifying the signature

Set a signing secret on the destination and Maple signs each body. The signature is the lowercase hex HMAC-SHA256 of the exact bytes of the request body, keyed with the secret, with no prefix. Compute it over the raw body before parsing the JSON, and compare in constant time.

import { createHmac, timingSafeEqual } from "node:crypto"

export function isFromMaple(rawBody: Buffer, signature: string | undefined, secret: string): boolean {
	if (!signature) return false
	const expected = createHmac("sha256", secret).update(rawBody).digest()
	const received = Buffer.from(signature, "hex")
	return received.length === expected.length && timingSafeEqual(received, expected)
}

import hashlib, hmac

def is_from_maple(raw_body: bytes, signature: str | None, secret: str) -> bool:
    if not signature:
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

The signature covers the body only, and the body carries no delivery timestamp you can trust for freshness, so a captured request could be replayed. Deduplicate on x-maple-delivery-key to make replays harmless.

Retries and failures

Alert events are attempted up to 5 times, about 1, 2, 4 and 8 minutes apart, with every retry carrying the same body and x-maple-delivery-key. Send test is attempted once.

After 3 consecutive non-retryable failures, the destination is disabled and the reason is shown on it under Alerts → Destinations. Fix the endpoint and re-enable it; a successful delivery resets the count.

Endpoint checklist

• Read the raw body, verify the signature, then parse.
• Return 2xx quickly and do slow work asynchronously; anything past 15 seconds is a failed attempt.
• Deduplicate on x-maple-delivery-key; retries are normal.
• Group by dedupeKey to follow one incident from trigger to resolve.
• Accept test events so Send test succeeds.