Docs

Alert e-mails from a self-hosted engine

Turn the alert webhook of your own engine into e-mail, with a small function on Amazon SES or a small server on any SMTP account.

Applies to Engine At launch

View as Markdown
On this page
  1. How it fits together
  2. The part both ways share
  3. Choose a sender
  4. Verify the sender in SES
  5. Create the function
  6. Write the server
  7. Run it
  8. Point the engine at it
  9. Check that it works
  10. What to know before you rely on it

Engine This guide is for whoever runs their own Sypnia engine and wants an e-mail when something breaks.

The default deployment of the engine sends no e-mail. It has no e-mail sender in it, on purpose: the engine stays small, and you choose the provider. What it does do is record every alert and post it to a webhook, if you set one. This guide puts a few lines of your own code on that webhook. On Sypnia Cloud you need none of this: alerts arrive by e-mail and in the app.

At the end you will have: an e-mail like this, within about two minutes of a new problem in production.

Text
Subject: [Shop] New problem: 1 person tried to pay and could not.

New problem: 1 person tried to pay and could not.

createPayment answered 400 in POST /api/checkout
1 person, 1 session, first seen 2026-03-12T09:12:04Z

Open it: https://sypnia.example.com/console/shop/problems/pay-button-does-nothing

You need: a running engine, an address you may send from, and either an AWS account (for SES) or an SMTP account from any provider.

How it fits together

  1. Something needs a person: a new problem, a problem that came back, your app not answering. The engine records an alert.
  2. The engine posts the alert to your webhook, signed.
  3. Your code checks the signature, writes the e-mail and hands it to SES or to your SMTP server.

The body of the post, with the fields this guide uses:

JSON
{
  "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",
      "created_at": "2026-03-12T09:13:02Z",
      "url": "https://sypnia.example.com/console/shop/problems/pay-button-does-nothing"
    },
    "problem": {
      "slug": "pay-button-does-nothing",
      "title": "createPayment answered 400 in POST /api/checkout",
      "sentence": null,
      "people": 1,
      "sessions": 1,
      "first_seen": "2026-03-12T09:12:04Z"
    }
  }
}

data.problem is there when the alert is about a problem; sentence is null until the agent has analysed it, and stays null when no model key is set. Every field, the other event types, the signature and the retries are in Alerts and webhooks.

The part both ways share

Save this file next to whichever sender you choose. It checks that a post really comes from your engine, and turns the event into an e-mail’s subject and text.

sypnia-alert.mjs
import { createHmac, timingSafeEqual } from 'node:crypto';

// True when the post was signed by your engine with the webhook secret, less than 5 minutes ago.
export function isFromSypnia(rawBody, header, secret) {
  const parts = Object.fromEntries(String(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);
}

// The e-mail for one alert, as plain text.
export function emailFor(event) {
  const { alert, problem } = event.data;
  const lines = [alert.title, ''];
  if (problem) {
    lines.push(problem.sentence ?? problem.title);
    lines.push(`${problem.people} ${problem.people === 1 ? 'person' : 'people'}, ${problem.sessions} ${problem.sessions === 1 ? 'session' : 'sessions'}, first seen ${problem.first_seen}`);
    lines.push('');
  }
  lines.push(`Open it: ${alert.url}`);
  return { subject: `[${event.project.name}] ${alert.title}`, text: lines.join('\n') };
}

Choose a sender

Amazon SES

A Lambda function with a Function URL receives the webhook and sends through SES.

  1. Verify the sender in SES

    In the Amazon SES console, verify the address or the domain you will send from, in the region you will use. A new SES account is in the sandbox and can only send to verified addresses; ask AWS for production access when you want to send to anyone.

    You should see
    The identity shows «Verified».
  2. Create the function

    Create a Lambda function on a current Node.js runtime, with a Function URL whose auth type is NONE (the signature is the check). Add sypnia-alert.mjs and this file:

    index.mjs
    import { SESv2Client, SendEmailCommand } from '@aws-sdk/client-sesv2';
    import { isFromSypnia, emailFor } from './sypnia-alert.mjs';
    
    const ses = new SESv2Client({});
    
    export async function handler(request) {
      const raw = request.isBase64Encoded ? Buffer.from(request.body ?? '', 'base64').toString('utf8') : request.body ?? '';
      if (!isFromSypnia(raw, request.headers['sypnia-signature'], process.env.SYPNIA_WEBHOOK_SECRET)) {
        return { statusCode: 401, body: 'bad signature' };
      }
    
      const event = JSON.parse(raw);
      if (event.type !== 'alert.created') return { statusCode: 200, body: 'ignored' };
    
      const { subject, text } = emailFor(event);
      await ses.send(new SendEmailCommand({
        FromEmailAddress: process.env.ALERTS_FROM,
        Destination: { ToAddresses: process.env.ALERTS_TO.split(',') },
        Content: { Simple: { Subject: { Data: subject }, Body: { Text: { Data: text } } } },
      }));
      return { statusCode: 200, body: 'sent' };
    }

    Set three environment variables on the function:

    Function environment
    SYPNIA_WEBHOOK_SECRET=<a long random string; the same value goes to the engine in the next section>
    ALERTS_FROM=alerts@shop.example
    ALERTS_TO=you@shop.example,teammate@shop.example

    Give the function’s role one permission, limited to your sender:

    IAM policy
    {
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Action": "ses:SendEmail",
        "Resource": "arn:aws:ses:us-east-1:123456789012:identity/shop.example"
      }]
    }
    You should see
    The function has a URL like https://abc123.lambda-url.us-east-1.on.aws/. Opening it in a browser answers bad signature: that is correct.

Point the engine at it

Add two settings to the engine and restart it. The secret is the same string you gave your receiver.

Engine environment
SYPNIA_ALERT_WEBHOOK_URL=https://abc123.lambda-url.us-east-1.on.aws/
SYPNIA_ALERT_WEBHOOK_SECRET=<the same long random string>

This webhook receives the alerts of every project of the engine. To send one project’s alerts somewhere else, register a webhook for that project through the API instead; its secret is created for you and shown once.

Check that it works

Terminal
sypnia doctor --only webhook
You should see
webhook ok, and your receiver answered 200. The check sends a signed ping, which the code above accepts and does not turn into an e-mail.

Then cause a real alert. Alerts are created for the production environment only, so run your app once with environment: 'production' and throw a test error, as in Your first problem.

You should see
An e-mail within about 2 minutes. The same alert is in the Console and in GET /v1/alerts, whether or not the e-mail worked.

What to know before you rely on it

  • Retries. If your receiver does not answer 2xx, the engine tries again later. A slow e-mail provider can therefore produce the same e-mail twice. Each event has an id that is the same on every retry: store the ids you have sent if duplicates matter to you.
  • No e-mail, no loss. An alert that could not be delivered is still recorded, and you can read it in the Console, the API and the CLI.
  • Which alerts. New problems, problems that came back or grow, uptime, slower pages, failing API routes and usage limits. The kinds and their thresholds are in Alerts and the daily summary; you can switch each one off.
  • The daily summary by e-mail is part of Sypnia Cloud. The engine does not produce it.
  • Keep the secret secret. Anyone who has it can make your function send e-mail.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close