Alerts and webhooks
Read alerts, tune the rules that create them, and register webhooks that receive them, signed and retried.
On this page
- The alert object
- The webhook object
- What a webhook receives
- Check the signature
- Take the raw body
- Compute the signature
- Compare, and check the time
- Retries
- List alerts
- Get an alert
- Acknowledge an alert
- List alert rules
- Update an alert rule
- List webhooks
- Create a webhook
- Get a webhook
- Update a webhook
- Delete a webhook
- List a webhook’s deliveries
- Send a test event
An alert is a record that says something needs a person: a new problem, a problem that came back, your app not answering. The engine always records alerts. What happens next depends on where you run:
| Sypnia engineOpen source, self-hosted | Sypnia CloudPaid service, with a free tier | |
|---|---|---|
| Recorded; listed by API, MCP and CLI | Yes | Yes |
| Sent to your webhooks | Yes | Yes |
| No. The default deployment has no e-mail sender. See the guide | Yes | |
| Shown to people | In the Console | In the app |
Alerts are created for the production environment only, unless you change a rule’s environments. There is no integration with chat apps: a webhook is the way to send an alert anywhere else.
A self-hosted engine can also send every alert of every project to one URL, without any call to this API: set SYPNIA_ALERT_WEBHOOK_URL. See the configuration reference.
The alert object
Fields
-
idstring optionalalt_…. -
kindstring optionalWhich rule created it. See the alert rules.
-
titlestring optionalThe alert in one line, ready to send to a person.
-
environmentstring optional -
subjectobject optionalWhat the alert is about.
-
subject.typestringOne of:
problem,uptime_check,page,api_route,project. -
subject.idstringThe problem’s or check’s id, or the route.
-
subject.slugstringProblems only.
-
created_attimestamp optional -
acknowledged_attimestamp or null optional -
acknowledged_bystring or null optionalWho acknowledged it, written like
resolved_byon a problem. -
urlURL optionalWhere to look, in the app or the Console.
The webhook object
Fields
-
idstring optionalwhk_…. -
urlURL optional -
eventsarray of string optional -
enabledboolean optional -
created_attimestamp optional -
last_deliveryobject or null optionalThe latest delivery and how it went.
-
disabled_reasonstring or null optionalfailingwhen the engine switched it off after 3 days of failed deliveries.
What a webhook receives
Each event is one POST to your URL with a JSON body.
| Event type | When |
|---|---|
alert.created | An alert was created. This is the one to forward to people |
problem.created | A problem was seen for the first time, in any environment |
problem.analyzed | The agent finished an analysis. data.problem.analysis has it |
problem.status_changed | A problem was resolved, reopened, ignored, or came back |
problem.pull_request_opened | Sypnia Cloud only: Sypnia opened a pull request |
ping | You created the webhook, or asked for a test |
Headers of a delivery
POST /hooks/sypnia HTTP/1.1
Content-Type: application/json
User-Agent: Sypnia-Webhooks/1.0
Sypnia-Event: alert.created
Sypnia-Delivery: dlv_2s4d6f8g0h1j
Sypnia-Attempt: 1
Sypnia-Signature: t=1773306783,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdBody of an `alert.created` delivery
{
"id": "evt_7m3n9b5v1c8x",
"type": "alert.created",
"created_at": "2026-03-12T09:13:02Z",
"project": { "id": "prj_5k2m9x4q7w1z", "slug": "shop", "name": "Shop" },
"data": {
"alert": {
"id": "alt_6w2e8r4t1y9u",
"kind": "problem.new",
"title": "New problem: 1 person tried to pay and could not.",
"environment": "production",
"subject": { "type": "problem", "id": "prb_8f3k2m9x4q7w", "slug": "pay-button-does-nothing" },
"created_at": "2026-03-12T09:13:02Z",
"acknowledged_at": null,
"acknowledged_by": null,
"url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing"
},
"problem": {
"id": "prb_8f3k2m9x4q7w",
"slug": "pay-button-does-nothing",
"status": "open",
"title": "createPayment answered 400 in POST /api/checkout",
"sentence": null,
"people": 1,
"sessions": 1,
"first_seen": "2026-03-12T09:12:04Z",
"url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing"
}
}
}Fields of every delivery
-
idstringThe event’s id,
evt_…. It is the same on every retry of the same event: store it and ignore an id you have already handled. -
typestringThe event type, as in the table above. Also in the
Sypnia-Eventheader. -
created_attimestampWhen the event happened, not when it was sent.
-
projectobjectThe project:
id,slug,name. -
dataobjectFor
alert.created:alert, plusproblemorcheckwhen the alert is about one. For theproblem.*types:problem, in the short form above, plusprevious_statusforproblem.status_changed. Forping: empty. An alert sent in the first 2 minutes of a problem may havesentenceset tonull: the alert does not wait for the agent beyond that.
Check the signature
Anyone who learns your URL can post to it. Check that a delivery comes from Sypnia before you act on it.
Sypnia-Signature has a timestamp t (seconds) and a signature v1. The signature is the HMAC-SHA256, in hex, of the timestamp, a dot and the raw body, keyed with the webhook’s secret (whsec_…).
Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';
export function isFromSypnia(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
if (!parts.t || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1);
return a.length === b.length && timingSafeEqual(a, b);
}Python
import hashlib, hmac, time
def is_from_sypnia(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if "t" not in parts or "v1" not in parts:
return False
if abs(time.time() - int(parts["t"])) > 300:
return False
signed = parts["t"].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])Retries
A delivery succeeds when your receiver answers any 2xx within 10 seconds. Answer first, then do slow work.
Anything else is retried, with the same evt_… id and a higher Sypnia-Attempt:
| Attempt | When |
|---|---|
| 1 | At once |
| 2 | 1 minute later |
| 3 | 5 minutes later |
| 4 | 30 minutes later |
| 5 | 2 hours later |
| 6 | 6 hours later |
| 7 | 12 hours later |
After the seventh failure the delivery is failed and is not tried again. When every delivery to a webhook has failed for 3 days, the engine switches the webhook off (disabled_reason is failing) and creates an engine.failing alert. Switch it back on with PATCH.
Deliveries may arrive out of order and, rarely, twice. Use the event’s id to ignore duplicates and created_at to order.
List alerts
/v1/alerts EngineCloud Alerts created in the time range, newest first.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403. -
kindstring optionalOnly alerts of this kind. See the alert rules for the list.
-
acknowledgedboolean optionalfalsereturns only alerts nobody has acknowledged. -
sincestring optionalOnly alerts created after this moment.
Default:
7d -
untilstring optionalEnd of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
-
limitinteger, 1 to 200 optionalMost items to return.
Default:
50 -
cursorstring optionalThe
next_cursorof the previous page. Keep every other parameter the same.
Request
curl "https://api.sypnia.com/v1/alerts?acknowledged=false" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"data": [
{
"id": "alt_6w2e8r4t1y9u",
"kind": "problem.new",
"title": "New problem: 1 person tried to pay and could not.",
"environment": "production",
"subject": {
"type": "problem",
"id": "prb_8f3k2m9x4q7w",
"slug": "pay-button-does-nothing"
},
"created_at": "2026-03-12T09:13:02Z",
"acknowledged_at": null,
"acknowledged_by": null,
"url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing"
}
],
"next_cursor": null
}Get an alert
/v1/alerts/{alert_id} EngineCloud One alert.
Path parameters
-
alert_idstring requiredThe alert’s id (
alt_…).
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Request
curl "https://api.sypnia.com/v1/alerts/alt_6w2e8r4t1y9u" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"id": "alt_6w2e8r4t1y9u",
"kind": "problem.new",
"title": "New problem: 1 person tried to pay and could not.",
"environment": "production",
"subject": {
"type": "problem",
"id": "prb_8f3k2m9x4q7w",
"slug": "pay-button-does-nothing"
},
"created_at": "2026-03-12T09:13:02Z",
"acknowledged_at": null,
"acknowledged_by": null,
"url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing"
}Errors
- 404
not_foundNo alert has this id in the project.
Acknowledge an alert
/v1/alerts/{alert_id}/acknowledge EngineCloud Records that someone saw the alert. It changes nothing else, the problem or check behind it keeps its status. Acknowledging twice answers 200 and keeps the first acknowledgement.
Path parameters
-
alert_idstring requiredThe alert’s id (
alt_…).
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Request
curl -X POST "https://api.sypnia.com/v1/alerts/alt_6w2e8r4t1y9u/acknowledge" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"id": "alt_6w2e8r4t1y9u",
"kind": "problem.new",
"title": "New problem: 1 person tried to pay and could not.",
"environment": "production",
"subject": {
"type": "problem",
"id": "prb_8f3k2m9x4q7w",
"slug": "pay-button-does-nothing"
},
"created_at": "2026-03-12T09:13:02Z",
"acknowledged_at": "2026-03-12T10:36:20Z",
"acknowledged_by": "token:Cursor",
"url": "https://app.sypnia.com/shop/problems/pay-button-does-nothing"
}Errors
- 404
not_foundNo alert has this id in the project.
List alert rules
/v1/alert-rules EngineCloud The rules that create alerts. The set is fixed: there is one rule per kind of alert, and you switch each one on or off and tune its thresholds. You cannot add kinds.
| Kind | Creates an alert when | Thresholds (defaults) |
|---|---|---|
problem.new | A problem is seen for the first time | None |
problem.regressed | A resolved problem happens again | None |
problem.growing | An open problem reaches twice the people it had at its last alert | factor 2, min_people 5 |
uptime.down | A check fails twice in a row | failures 2 |
uptime.recovered | A check that was down answers again | None |
page.slower | A page’s LCP at p75 over the last 24 hours grew against the 7 days before | increase_percent 30, min_views 50 |
api.failing | An API route answers 5xx or nothing too often over the last hour | error_rate_percent 2, min_requests 50 |
usage.limit | The project reaches a share of a usage limit | percents 80 and 100 |
engine.failing | Processing has not caught up for 30 minutes, or webhook deliveries keep failing | None |
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Request
curl "https://api.sypnia.com/v1/alert-rules" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN"Response200
{
"data": [
{
"kind": "problem.new",
"enabled": true,
"environments": [
"production"
],
"thresholds": {}
},
{
"kind": "problem.regressed",
"enabled": true,
"environments": [
"production"
],
"thresholds": {}
},
{
"kind": "problem.growing",
"enabled": true,
"environments": [
"production"
],
"thresholds": {
"factor": 2,
"min_people": 5
}
},
{
"kind": "uptime.down",
"enabled": true,
"environments": [
"production"
],
"thresholds": {
"failures": 2
}
},
{
"kind": "uptime.recovered",
"enabled": true,
"environments": [
"production"
],
"thresholds": {}
},
{
"kind": "page.slower",
"enabled": true,
"environments": [
"production"
],
"thresholds": {
"increase_percent": 30,
"min_views": 50
}
},
{
"kind": "api.failing",
"enabled": true,
"environments": [
"production"
],
"thresholds": {
"error_rate_percent": 2,
"min_requests": 50
}
},
{
"kind": "usage.limit",
"enabled": true,
"environments": [
"production"
],
"thresholds": {
"percents": [
80,
100
]
}
},
{
"kind": "engine.failing",
"enabled": true,
"environments": [
"production"
],
"thresholds": {}
}
]
}Update an alert rule
/v1/alert-rules/{kind} EngineCloud Switches a rule on or off, changes the environments it watches, or changes its thresholds. Send only what changes; thresholds are merged key by key.
Path parameters
-
kindstring requiredThe rule’s kind, for example
page.slower. One of:problem.new,problem.regressed,problem.growing,uptime.down,uptime.recovered,page.slower,api.failing,usage.limit,engine.failing.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Body
-
enabledboolean optionalfalsestops this kind of alert. -
environmentsarray of string optionalThe environments the rule watches.
-
thresholdsobject optionalThe thresholds to change, by name. See the table of rules.
Request
curl -X PATCH "https://api.sypnia.com/v1/alert-rules/page.slower" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"thresholds": {"increase_percent": 50}}'Response200
{
"kind": "page.slower",
"enabled": true,
"environments": [
"production"
],
"thresholds": {
"increase_percent": 50,
"min_views": 50
}
}Errors
- 400
invalid_requestA threshold is unknown for this kind or out of range.
paramnames it. - 404
not_foundNo rule has this kind.
List webhooks
/v1/webhooks EngineCloud The project’s webhooks. Secrets are not shown.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Request
curl "https://api.sypnia.com/v1/webhooks" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"Response200
{
"data": [
{
"id": "whk_4z6x8c2v0b1n",
"url": "https://shop.example.com/hooks/sypnia",
"events": [
"alert.created",
"problem.analyzed"
],
"enabled": true,
"created_at": "2026-02-02T09:25:00Z",
"last_delivery": {
"at": "2026-03-12T10:33:06Z",
"status": "delivered",
"response_status": 200
},
"disabled_reason": null
}
],
"next_cursor": null
}Create a webhook
/v1/webhooks EngineCloud Registers a URL of yours to receive events. The signing secret is in secret and is shown only in this
answer. The URL must be https (a self-hosted engine also accepts http when
SYPNIA_WEBHOOKS_ALLOW_HTTP is true, for a receiver inside your own network).
The engine sends a ping event right after creation, so you can see your receiver work.
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Headers
-
Idempotency-Keystring, up to 255 characters optionalA value of your own, 1 to 255 characters, that makes the call safe to repeat. See idempotency.
Body
-
urlURL, up to 2,000 characters requiredWhere to send events.
-
eventsarray of string optionalThe event types to send.
problem.pull_request_openedonly happens on Sypnia Cloud. One of:alert.created,problem.created,problem.analyzed,problem.status_changed,problem.pull_request_opened.Default:
['alert.created'] -
enabledboolean optionalfalsecreates it paused.Default:
true
Request
curl -X POST "https://api.sypnia.com/v1/webhooks" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url": "https://shop.example.com/hooks/sypnia", "events": ["alert.created", "problem.analyzed"]}'Response201
{
"id": "whk_4z6x8c2v0b1n",
"url": "https://shop.example.com/hooks/sypnia",
"events": [
"alert.created",
"problem.analyzed"
],
"enabled": true,
"secret": "whsec_Jt5nQ8rV2xZ7cB4mK9pL1dF6hS3gA0wE",
"created_at": "2026-02-02T09:25:00Z",
"last_delivery": null,
"disabled_reason": null
}Errors
- 400
invalid_requestThe URL is not
https, resolves to a private address (Sypnia Cloud), oreventshas an unknown type. - 409
limit_reachedThe project already has 10 webhooks.
Get a webhook
/v1/webhooks/{webhook_id} EngineCloud One webhook, without its secret.
Path parameters
-
webhook_idstring requiredThe webhook’s id (
whk_…).
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Request
curl "https://api.sypnia.com/v1/webhooks/whk_4z6x8c2v0b1n" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"Response200
{
"id": "whk_4z6x8c2v0b1n",
"url": "https://shop.example.com/hooks/sypnia",
"events": [
"alert.created",
"problem.analyzed"
],
"enabled": true,
"created_at": "2026-02-02T09:25:00Z",
"last_delivery": {
"at": "2026-03-12T10:33:06Z",
"status": "delivered",
"response_status": 200
},
"disabled_reason": null
}Errors
- 404
not_foundNo webhook has this id in the project.
Update a webhook
/v1/webhooks/{webhook_id} EngineCloud Changes the URL, the events or enabled. Setting enabled to true on a webhook the engine disabled starts deliveries again. Send rotate_secret as true to get a new secret, shown only in this answer; the old one stops working at once.
Path parameters
-
webhook_idstring requiredThe webhook’s id (
whk_…).
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Body
-
urlURL, up to 2,000 characters optionalWhere to send events.
-
eventsarray of string optionalThe event types to send. Replaces the list.
-
enabledboolean optionalfalsepauses deliveries; events that happen meanwhile are not sent later. -
rotate_secretboolean optionaltruereplaces the signing secret.Default:
false
Request
curl -X PATCH "https://api.sypnia.com/v1/webhooks/whk_4z6x8c2v0b1n" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"events": ["alert.created"]}'Response200
{
"id": "whk_4z6x8c2v0b1n",
"url": "https://shop.example.com/hooks/sypnia",
"events": [
"alert.created"
],
"enabled": true,
"created_at": "2026-02-02T09:25:00Z",
"last_delivery": {
"at": "2026-03-12T10:33:06Z",
"status": "delivered",
"response_status": 200
},
"disabled_reason": null
}Errors
- 404
not_foundNo webhook has this id in the project.
Delete a webhook
/v1/webhooks/{webhook_id} EngineCloud Deletes the webhook and stops its pending deliveries.
Path parameters
-
webhook_idstring requiredThe webhook’s id (
whk_…).
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Request
curl -X DELETE "https://api.sypnia.com/v1/webhooks/whk_4z6x8c2v0b1n" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"Errors
- 404
not_foundNo webhook has this id in the project.
List a webhook’s deliveries
/v1/webhooks/{webhook_id}/deliveries EngineCloud What was sent to the webhook and how your receiver answered, newest first. Deliveries are kept for 30 days. Use it to find out why an alert did not arrive.
Path parameters
-
webhook_idstring requiredThe webhook’s id (
whk_…).
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403. -
statusstring optionalOnly deliveries in this status. One of:
pending,delivered,failed. -
limitinteger, 1 to 200 optionalMost items to return.
Default:
50 -
cursorstring optionalThe
next_cursorof the previous page. Keep every other parameter the same.
Request
curl "https://api.sypnia.com/v1/webhooks/whk_4z6x8c2v0b1n/deliveries?status=failed" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"Response200
{
"data": [
{
"id": "dlv_2s4d6f8g0h1j",
"event_id": "evt_7m3n9b5v1c8x",
"event_type": "alert.created",
"status": "delivered",
"attempts": 1,
"response_status": 200,
"response_ms": 142,
"created_at": "2026-03-12T09:13:03Z",
"delivered_at": "2026-03-12T09:13:03Z",
"next_attempt_at": null,
"error": null
}
],
"next_cursor": null
}Errors
- 404
not_foundNo webhook has this id in the project.
Send a test event
/v1/webhooks/{webhook_id}/test EngineCloud Sends a ping event to the webhook now, signed like a real one, and answers with what your receiver said. It is not retried and not stored as a delivery.
Path parameters
-
webhook_idstring requiredThe webhook’s id (
whk_…).
Query parameters
-
projectstring optionalThe project’s id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is
403.
Request
curl -X POST "https://api.sypnia.com/v1/webhooks/whk_4z6x8c2v0b1n/test" \
-H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"Response200
{
"ok": true,
"response_status": 200,
"response_ms": 131,
"error": null
}Errors
- 404
not_foundNo webhook has this id in the project.
The errors every endpoint can answer (401, 403, 429, 500, 503) are on Errors, limits, pagination.