Docs

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.

Aplica a Motor Al lanzar

Ver como Markdown
En esta página
  1. Cómo encaja todo
  2. La parte que comparten los dos caminos
  3. Elige un emisor
  4. Verifica el remitente en SES
  5. Crea la función
  6. Escribe el servidor
  7. Córrelo
  8. Apunta el motor hacia él
  9. Comprueba que funciona
  10. Qué saber antes de depender de esto

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.

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

Necesitas: 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

  1. Algo necesita a una persona: un problema nuevo, un problema que volvió, tu app que no responde. El motor registra una alerta.
  2. El motor envía la alerta a tu webhook, firmada.
  3. 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:

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 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.

sypnia-alert.mjs
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.

  1. 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 ver
    La identidad muestra «Verified».
  2. 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). Agrega sypnia-alert.mjs y 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.example

    Dale 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 ver
    La función tiene una URL como https://abc123.lambda-url.us-east-1.on.aws/. Abrirla en un navegador responde bad signature: eso es lo correcto.

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.

Entorno del motor
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

Terminal
sypnia doctor --only webhook
Deberías ver
webhook 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.

Deberías ver
Un correo en unos 2 minutos. La misma alerta está en la Consola y en 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 un id que 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.

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar