Hermes recibe webhooks de GitHub y Dokploy de Grupo Secovam y publica avisos en Campfire. También recibe altas de AppSheet, envía un acuse por Resend y avisa en una sala exclusiva cuando Resend acepta el correo. AppSheet usa un ledger SQLite persistente. GitHub y Dokploy siguen sin estado persistente.
- Runtime: Bun
- Framework: Hono
- Validación: Zod
- Linting: Ultracite (oxlint + oxfmt)
| Evento | Condición | Mensaje |
|---|---|---|
push |
Rama main |
📝 repo · sha7 mensaje — autor |
pull_request.opened |
Todas las ramas | 🔀 repo · PR #n título abierto por autor |
pull_request.closed |
Mergeado | ✅ repo · PR #n título mergeado por autor |
pull_request.closed |
Sin merge | ❌ repo · PR #n título cerrado sin merge |
issues.opened |
— | 🐛 repo · issue #n título por autor |
issues.closed |
— | ☑️ repo · issue #n título cerrado |
release.published |
— | 🚀 repo · release tag publicada |
workflow_run.completed |
Fallo en main o en un PR |
💥 repo · workflow nombre falló en main o en PR #n |
issue_comment.created |
PR, CodeRabbit | 💬 repo · CodeRabbit comentó en PR #n título |
pull_request_review_comment.created |
CodeRabbit | 💬 repo · CodeRabbit comentó en un archivo del PR |
Los comentarios de CodeRabbit se publican en CAMPFIRE_REVIEW_ROOM_URL con una vista previa breve y el enlace Ver comentario en GitHub, que abre el comentario exacto. Si el comentario incluye un <summary>, Hermes muestra ese texto; de lo contrario, usa un extracto del cuerpo.
GITHUB_WEBHOOK_SECRET=xxx # secreto del webhook org-level
CAMPFIRE_ROOM_URL=https://campfire.ejemplo.com/rooms/123/bot/abc/messages
CAMPFIRE_CI_ROOM_URL=https://campfire.ejemplo.com/rooms/456/bot/def/messages # fallos de CI en main y PR
CAMPFIRE_REVIEW_ROOM_URL=https://campfire.ejemplo.com/rooms/789/bot/ghi/messages # CodeRabbit y Macroscope
PORT=3000
LOG_LEVEL=info # debug, info, warn, errorHermes envía una notificación por cada ejecución fallida de un workflow en main o asociada a un PR. Configura CAMPFIRE_CI_ROOM_URL para la sala dedicada de CI. Si falta, Hermes devuelve un error para ese webhook.
Los workflows disparados por pull_request o pull_request_target también se incluyen cuando GitHub no adjunta números de PR. En ese caso, el aviso identifica la rama del PR.
# Instalar dependencias
bun install
# Desarrollo con hot reload
bun run dev
# Verificar código
bun run check
# Formatear código
bun run fixPOST /appsheet requiere Authorization: Bearer <APPSHEET_WEBHOOK_TOKEN> incluso en desarrollo. Solo acepta la app y tabla configuradas. /webhook sigue reservado para GitHub.
{
"appId": "appsheet-app-id",
"table": "Solicitudes",
"event": "record.created",
"recordId": "MTTO-00042",
"email": "persona@example.com",
"name": "Ana"
}El objeto es estricto y el límite del cuerpo es 16 KiB, incluso sin Content-Length. appId, table y recordId admiten de 1 a 200 caracteres. email debe ser válido y tener como máximo 254 caracteres. name admite hasta 200 y puede estar vacío. No se aceptan campos para asunto, remitente ni HTML.
event decide el correo. Todos usan el folio como recordId, así que los bots de MANTENIMIENTOS también envían el folio de la solicitud y table igual a APPSHEET_TABLE.
event |
Asunto | Campo extra |
|---|---|---|
record.created |
Solicitud recibida |
ninguno |
maintenance.started |
Mantenimiento iniciado |
ninguno |
maintenance.finished |
Mantenimiento terminado - <folio> |
ninguno |
approval.confirmed |
Visto bueno confirmado |
reportUrl, HTTPS, hasta 2000 |
approval.rejected |
Visto bueno rechazado - <folio> |
reason, no vacío, hasta 2000 |
Cada evento se envía una sola vez por folio. Una solicitud reabierta no repite un correo ya aceptado para el mismo evento.
Los textos de cada correo están en src/emails/maintenance-request.tsx. recordId debe ser el folio de la solicitud, por ejemplo MTTO-00042. La versión HTML incrusta el logo de Grupo Secovam como adjunto inline (cid:), sigue el estilo de los correos de Kerberos con React Email (src/emails/maintenance-request.tsx). name no aparece en el correo.
Las siete variables son obligatorias para esta ruta. Si alguna falta o es inválida, responde 503 sin efectos. Las demás integraciones siguen disponibles.
| Variable | Uso |
|---|---|
APPSHEET_WEBHOOK_TOKEN |
Token privado compartido con el bot AppSheet. |
APPSHEET_APP_ID |
ID exacto de la app autorizada. |
APPSHEET_TABLE |
Nombre exacto de la tabla autorizada. |
RESEND_API_KEY |
Clave con permiso de envío en Resend. |
RESEND_FROM |
Remitente del dominio verificado en Resend. |
APPSHEET_DB_PATH |
Ruta absoluta, por ejemplo /data/hermes.sqlite. |
CAMPFIRE_EMAIL_ROOM_URL |
URL HTTPS del bot de la sala exclusiva de correos. |
El aviso dice Correo aceptado para envío e identifica destinatario, asunto, app, tabla, ID del registro y resend_id. No contiene el cuerpo del correo. La sala es obligatoria y nunca se sustituye por la general. Sus miembros deben estar autorizados para ver direcciones de correo. accepted significa que Resend aceptó la petición, no que el buzón recibió el correo.
Estos pasos son posteriores a la implementación local y requieren autorización de producción. Esta entrega no activa bots ni envía mensajes reales.
- Verifica el dominio y remitente en Resend y provisiona su clave de envío. Revisa destinatario y texto del acuse con negocio.
- Crea una sala exclusiva en Campfire, limita sus miembros y configura su bot. Guarda la URL como
CAMPFIRE_EMAIL_ROOM_URL. - Configura las siete variables en Dokploy mediante su gestor de secretos. Comparte secretos solo por el mecanismo seguro de la sesión, nunca por chat ni git.
- Monta un volumen persistente en
/datapara una sola instancia de Hermes. UsaAPPSHEET_DB_PATH=/data/hermes.sqlite. El usuario del contenedor tiene UID y GID65532. Un bind mount debe ser escribible por ese usuario y tener permisos0700en el directorio. La imagen prepara/datacon esos permisos. - En AppSheet, crea un bot para Adds en la tabla autorizada. Elige evento App para altas mediante la app o AppSheet database para cambios directos en esa base. Un cambio directo en otra fuente externa puede requerir configuración adicional. Consulta los eventos de AppSheet.
- Añade una tarea Call a webhook, preset Custom, verbo POST, contenido JSON, URL
https://<host-hermes>/appsheety headerAuthorization: Bearer <token>. Usa el contrato anterior para el body. Consulta la configuración oficial de webhooks. - Vincula
recordIda la clave permanente de la fila. Nunca usesNOW(), número de fila o unUNIQUEID()nuevo por intento. Conserva tambiénemailynameentre reintentos de la misma alta. - Verifica el JSON expandido antes de habilitar el bot. Escapa comillas como
\", barras inversas como\\, y saltos de línea como\n. No concatentes valores sin escape. Un nombre con comillas y salto debe producir JSON como"name": "Ana \"López\"\nPérez". No apliques doble escape si AppSheet ya serializa el valor. La verificación local cubrió estos caracteres en Hermes, no la expansión de una plantilla AppSheet real. - Mantén el reloj del host sincronizado. Configura un timeout del proxy y webhook superior a los dos envíos de hasta 20 segundos cada uno. Hermes usa un timeout de inactividad de 60 segundos.
La identidad es el SHA-256 completo de JSON.stringify([appId, table, event, recordId]). La clave del proveedor es appsheet/<hash>. Un segundo SHA-256 de JSON.stringify([email, name]), más reason o reportUrl cuando existen, detecta cambios de datos para esa identidad. Un nuevo recordId produce un nuevo correo y aviso.
Antes de enviar, SQLite conserva el JSON exacto de Resend. Todo reintento reutiliza esos bytes, aunque cambien remitente o plantilla. Un lease de 60 segundos reserva el correo a un propietario. Los reintentos inciertos solo se permiten antes de 23 horas desde el primer intento, que nunca se reinicia. Resend documenta una ventana de idempotencia de 24 horas. El margen depende de un reloj correcto. Véase idempotencia en Resend.
Tras persistir accepted y resend_id, Hermes reserva el aviso con pending -> sending. Solo quien reserva publica en Campfire. Un correo aceptado nunca se repite, tampoco días después. Si el proceso cae antes de reservar el aviso, el próximo webhook publica solo ese aviso. Una reserva sending o uncertain nunca se libera por antigüedad.
| HTTP | Resultado |
|---|---|
200 processed |
Correo aceptado y aviso confirmado como publicado. |
200 already_processed |
Ambos efectos ya estaban confirmados. Sin nuevos envíos. |
400 / 401 / 403 / 413 |
JSON o payload inválido, token inválido, origen no autorizado o exceso de cuerpo. Sin efectos. |
409 payload_conflict |
Misma identidad con distinto email o nombre. Sin nuevos efectos. |
409 needs_review |
Rechazo previo, conflicto del proveedor, correo incierto fuera de ventana o aviso reservado sin confirmación. |
502 email_not_confirmed |
Respuesta incierta o rechazo definitivo de Resend. Un rechazo queda bloqueado para revisión. |
502 campfire_not_confirmed |
Correo aceptado, aviso incierto. El próximo webhook requiere revisión y no repite efectos. |
503 |
Configuración o DB no disponible, lease vigente, rate limit o petición concurrente del proveedor. |
No hay worker ni cola. Revisa AppSheet Monitor y los logs cuando se agoten los reintentos. La verificación local simuló idempotencia del proveedor y contó solicitudes por separado de las aceptaciones. No probó idempotencia externa, entrega SMTP ni publicación real. Los archivos de pruebas se retiraron por decisión del usuario.
SQLite usa WAL, synchronous=FULL, consultas parametrizadas y transacciones cortas sin esperar red. El archivo se crea con permisos 0600 porque guarda datos personales. Protege también el directorio, backups y archivos WAL y SHM. .gitignore y .dockerignore excluyen data/, .sqlite*, .db, .db-wal y .db-shm; conserva estos nombres para archivos y copias locales.
No hay TTL. Perder el volumen o restaurar una copia antigua puede repetir correos y avisos. Usa la API de backup consistente de SQLite o detén Hermes antes de copiar el conjunto de archivos de la base. No copies únicamente el archivo principal de una base activa en WAL. Conserva la copia protegida fuera del repositorio.
Para un needs_review, correlaciona el key de los logs con notifications.key, payload_hash, first_attempt_at, resend_id y los estados. Inspecciona la base de forma local y restringida, sin volcar cuerpos ni credenciales en logs. Los timestamps se expresan en milisegundos Unix.
- Detén entradas AppSheet y espera a que no haya peticiones en curso. Obtén un backup consistente antes de cualquier modificación.
- Para un correo incierto, busca evidencia de aceptación en Resend usando la clave
appsheet/<key>, destinatario y hora original. Solo evidencia verificable permite confirmaraccepted, su ID y el HTML determinista del aviso. Si no hay evidencia, mantén el bloqueo. No inventes una nueva clave ni reinicies la fecha del primer intento. - Para un aviso incierto, busca en la sala dedicada por ID del registro y
resend_id. Si existe, una operación revisada puede confirmarposted. Si no se encuentra, eso no demuestra ausencia. Conserva la reserva hasta acordar una operación concreta y autorizada. - Prepara y revisa cada actualización con condiciones sobre clave, hash y estado esperado. No ejecutes resets genéricos. Hermes no expone un endpoint público de recuperación ni borra reservas automáticamente.
El ledger evita reintentos ciegos. Un aviso incierto puede faltar hasta la conciliación manual. No garantiza entrega exactamente una vez.
-
Crear servicio en Dokploy:
- Tipo: Docker
- Dockerfile:
Dockerfile - Puerto:
3000
-
Configurar variables de entorno en Dokploy (ver sección anterior)
-
Crear webhook org-level en GitHub:
- Ir a: https://github.com/organizations/Secovam/settings/hooks
- Payload URL:
https://hermes.tudominio.com/webhook - Content type:
application/json - Secret: el mismo valor de
GITHUB_WEBHOOK_SECRET - Eventos:
push,pull_request,pull_request_review_comment,issue_comment,issues,release,workflow_run
-
Verificar:
- Hacer un commit a
mainen un repo de Secovam - Debería aparecer el mensaje en Campfire
- Hacer un commit a
# Terminal 1: iniciar servidor
bun run dev
# Terminal 2: exponer con ngrok
ngrok http 3000
# Configurar webhook en GitHub apuntando a la URL de ngrokLos logs están en formato JSON estructurado (wide events):
{
"level": "info",
"timestamp": "2026-04-23T...",
"msg": "webhook completed",
"event": "push",
"repo": "secovam/repo",
"action": null,
"delivery_id": "abc123",
"duration_ms": 150,
"status": "success"
}