Correos de alerta desde un motor con alojamiento propio
Convierte en correo el webhook de alertas de tu propio motor, con una función pequeña sobre Amazon SES o un servidor pequeño sobre cualquier cuenta SMTP.
Motor Esta guía es para quien corre su propio motor de Sypnia y quiere un correo cuando algo se rompe.
El despliegue por defecto del motor no envía correos. No trae un emisor de correo, a propósito: el motor se mantiene pequeño, y tú eliges el proveedor. Lo que sí hace es registrar cada alerta y enviarla a un webhook, si pones uno. Esta guía pone unas pocas líneas de tu propio código en ese webhook. En Sypnia Cloud no necesitas nada de esto: las alertas llegan por correo y dentro de la app.
Al final tendrás: un correo como este, unos dos minutos después de un problema nuevo en producción.
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-nothingNecesitas: un motor corriendo, una dirección desde la que puedas enviar, y una cuenta de AWS (para SES) o una cuenta SMTP de cualquier proveedor.
Cómo encaja todo
- Algo necesita a una persona: un problema nuevo, un problema que volvió, tu app que no responde. El motor registra una alerta.
- El motor envía la alerta a tu webhook, firmada.
- Tu código revisa la firma, escribe el correo y se lo entrega a SES o a tu servidor SMTP.
El cuerpo del envío, con los campos que usa esta guía:
{
"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 viene cuando la alerta es sobre un problema; sentence es null hasta que el agente lo analiza, y sigue en null cuando no hay llave de modelo. Cada campo, los demás tipos de evento, la firma y los reintentos están en Alertas y webhooks.
La parte que comparten los dos caminos
Guarda este archivo junto al emisor que elijas. Revisa que un envío venga de verdad de tu motor, y convierte el evento en el asunto y el texto de un correo.
import { createHmac, timingSafeEqual } from 'node:crypto';
// Verdadero cuando tu motor firmó el envío con el secreto del webhook, hace menos de 5 minutos.
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);
}
// El correo de una alerta, como texto simple.
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') };
}Elige un emisor
Amazon SES
Una función Lambda con una Function URL recibe el webhook y envía por SES.
Verifica el remitente en SES
En la consola de Amazon SES, verifica la dirección o el dominio desde el que vas a enviar, en la región que vas a usar. Una cuenta nueva de SES está en el sandbox y solo puede enviar a direcciones verificadas; pídele a AWS acceso de producción cuando quieras enviar a cualquiera.
Deberías verLa identidad muestra «Verified».Crea la función
Crea una función Lambda con un runtime actual de Node.js, con una Function URL cuyo tipo de autenticación sea
NONE(la firma es el control). Agregasypnia-alert.mjsy este archivo: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' }; }Pon tres variables de entorno en la función:
Entorno de la función SYPNIA_WEBHOOK_SECRET=<un texto largo y aleatorio; el mismo valor va al motor en la siguiente sección> ALERTS_FROM=alerts@shop.example ALERTS_TO=you@shop.example,teammate@shop.exampleDale al rol de la función un solo permiso, limitado a tu remitente:
Política de IAM { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "ses:SendEmail", "Resource": "arn:aws:ses:us-east-1:123456789012:identity/shop.example" }] }Deberías verLa función tiene una URL comohttps://abc123.lambda-url.us-east-1.on.aws/. Abrirla en un navegador respondebad signature: eso es lo correcto.
Cualquier SMTP
Un servidor Node pequeño recibe el webhook y envía por tu cuenta SMTP. Córrelo en cualquier lugar al que tu motor pueda llegar: la misma máquina sirve.
Escribe el servidor
Terminal npm init -y && npm install nodemailerserver.mjs import { createServer } from 'node:http'; import nodemailer from 'nodemailer'; import { isFromSypnia, emailFor } from './sypnia-alert.mjs'; const mail = nodemailer.createTransport({ host: process.env.SMTP_HOST, port: Number(process.env.SMTP_PORT ?? 587), auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASSWORD }, }); createServer(async (req, res) => { const chunks = []; for await (const chunk of req) chunks.push(chunk); const raw = Buffer.concat(chunks).toString('utf8'); if (req.method !== 'POST' || !isFromSypnia(raw, req.headers['sypnia-signature'], process.env.SYPNIA_WEBHOOK_SECRET)) { res.writeHead(401).end('bad signature'); return; } const event = JSON.parse(raw); if (event.type === 'alert.created') { const { subject, text } = emailFor(event); await mail.sendMail({ from: process.env.ALERTS_FROM, to: process.env.ALERTS_TO, subject, text }); } res.writeHead(200).end('ok'); }).listen(Number(process.env.PORT ?? 8787));Córrelo
Terminal SYPNIA_WEBHOOK_SECRET=<un texto largo y aleatorio> \ SMTP_HOST=smtp.example.com SMTP_PORT=587 SMTP_USER=alerts@shop.example SMTP_PASSWORD=<contraseña> \ ALERTS_FROM=alerts@shop.example ALERTS_TO=you@shop.example \ node server.mjsDeberías verEl servidor escucha en el puerto 8787.curl -i -X POST http://localhost:8787responde401 bad signature: eso es lo correcto.Si al receptor se llega por
httpsimple o por una dirección privada, ponSYPNIA_WEBHOOKS_ALLOW_HTTP=trueen el motor. Mantenlo corriendo con lo mismo que mantiene corriendo tus otros servicios.
Apunta el motor hacia él
Agrega dos ajustes al motor y reinícialo. El secreto es el mismo texto que le diste a tu receptor.
SYPNIA_ALERT_WEBHOOK_URL=https://abc123.lambda-url.us-east-1.on.aws/
SYPNIA_ALERT_WEBHOOK_SECRET=<el mismo texto largo y aleatorio>Este webhook recibe las alertas de todos los proyectos del motor. Para enviar las alertas de un proyecto a otro lugar, registra un webhook para ese proyecto con la API; su secreto se crea por ti y se muestra una sola vez.
Comprueba que funciona
sypnia doctor --only webhookwebhook ok, y tu receptor respondió 200. El chequeo envía un ping firmado, que el código de arriba acepta y no convierte en correo.Luego causa una alerta real. Las alertas se crean solo para el entorno production, así que corre tu app una vez con environment: 'production' y lanza un error de prueba, como en Tu primer problema.
GET /v1/alerts, haya funcionado o no el correo.Qué saber antes de depender de esto
- Reintentos. Si tu receptor no responde
2xx, el motor lo intenta de nuevo más tarde. Un proveedor de correo lento puede producir entonces el mismo correo dos veces. Cada evento tiene unidque es el mismo en cada reintento: guarda los ids que ya enviaste si los duplicados te importan. - Sin correo no hay pérdida. Una alerta que no se pudo entregar igual queda registrada, y la puedes leer en la Consola, la API y el CLI.
- Qué alertas. Problemas nuevos, problemas que volvieron o que crecen, disponibilidad, páginas más lentas, rutas de la API que fallan y límites de uso. Las clases y sus umbrales están en Alertas y el resumen diario; puedes apagar cada una.
- El resumen diario por correo es parte de Sypnia Cloud. El motor no lo produce.
- Guarda bien el secreto. Quien lo tenga puede hacer que tu función envíe correos.