Webhooks y programaciones.

Un trigger lanza una automatización sin ti: un webhook cuando GitHub, Stripe o uno de tus sistemas envía un evento, o una programación a las horas que elijas. Cada arranque crea un run en tu workspace con los ajustes de la automatización, exactamente igual que Run now.

Una automatización puede tener hasta 5 triggers, de cualquiera de los dos tipos. Los gestionas en su pestaña Triggers, en cloud.nan.builders/automations: + Webhook, + Schedule y, en cada trigger, Pause / Resume, Rotate (webhooks) y el icono de la papelera para borrarlo. Añadir, cambiar y borrar triggers exige una sesión en el navegador.

Añade un webhook

Desde GitHub

En el repositorio, abre Settings → Webhooks → Add webhook (o lo mismo en los ajustes de tu organización):

GitHub firma cada entrega con X-Hub-Signature-256 y NaN la comprueba. Al guardar, GitHub envía un ping: se ignora siempre y aparece como Ignored by a filter en Deliveries. Eso te dice que la URL y el secreto funcionan.

GitHub no firma ninguna marca de tiempo, así que NaN recuerda el id de cada entrega (X-GitHub-Delivery) y lanza como mucho un run por entrega durante 30 días. Redeliver en GitHub envía el mismo id: si ya lanzó un run, se responde como duplicado.

Desde Stripe

NaN comprueba Stripe-Signature, acepta cualquiera de las firmas que envía Stripe (envía varias mientras rotas su secreto) y rechaza los eventos con más de 5 minutos de desfase. Funcionan tanto el modo test como el live: el endpoint que creas decide qué eventos recibes. Cada id de evento (evt_...) lanza como mucho un run.

Envía tus propios eventos

El emisor NaN (HMAC) es para tus propios sistemas: un script de despliegue, una alerta de monitorización, otro servicio. Envía un POST con un objeto JSON como cuerpo y estas cabeceras:

Firma el cuerpo exactamente como lo envías, byte a byte. En bash:

URL="https://api.nan.builders/hooks/nan_whk_..."
SECRET="..."                       # el secreto de firma
BODY='{"service":"api","version":"1.4.2"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

curl -s "$URL" \
  -H "Content-Type: application/json" \
  -H "X-Nan-Timestamp: $TS" \
  -H "X-Nan-Signature: v1=$SIG" \
  -H "X-Nan-Event: deploy.finished" \
  -d "$BODY"

En Python:

import hashlib, hmac, json, time, urllib.request

url = "https://api.nan.builders/hooks/nan_whk_..."
secret = b"..."
body = json.dumps({"service": "api", "version": "1.4.2"}).encode()
ts = str(int(time.time()))
sig = hmac.new(secret, ts.encode() + b"." + body, hashlib.sha256).hexdigest()

req = urllib.request.Request(url, data=body, method="POST", headers={
    "Content-Type": "application/json",
    "X-Nan-Timestamp": ts,
    "X-Nan-Signature": f"v1={sig}",
    "X-Nan-Event": "deploy.finished",
})
print(urllib.request.urlopen(req).read().decode())

En Node.js:

import { createHmac } from 'node:crypto';

const url = 'https://api.nan.builders/hooks/nan_whk_...';
const secret = '...';
const body = JSON.stringify({ service: 'api', version: '1.4.2' });
const ts = Math.floor(Date.now() / 1000).toString();
const sig = createHmac('sha256', secret).update(`${ts}.${body}`).digest('hex');

const res = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Nan-Timestamp': ts,
    'X-Nan-Signature': `v1=${sig}`,
    'X-Nan-Event': 'deploy.finished',
  },
  body,
});
console.log(res.status, await res.text());

Filtros de eventos

El Event filter es un objeto JSON. Cada lista que rellenes tiene que coincidir, y una lista vacía lo deja pasar todo. Si dejas el campo vacío, el webhook usa el filtro de la plantilla de la automatización (cuando el emisor es el de la plantilla); para dejar pasar todos los eventos, escribe {}:

La plantilla Pull request review, por ejemplo, usa:

{
  "events": ["pull_request"],
  "actions": ["opened", "synchronize", "reopened", "ready_for_review"],
  "exclude_drafts": true
}

Hasta 32 entradas por lista, cada una con caracteres de A-Z a-z 0-9 _ . : -. Un evento que no coincide se responde con 200 y aparece como Ignored by a filter.

Solo algunos usuarios de GitHub

Por defecto, cualquier evento con una firma válida lanza un run. En un repositorio público, eso significa cualquiera que pueda abrir una pull request o una issue. Para limitarlo, marca Only some GitHub users en Who can start it:

• GitHub logins: solo los eventos enviados por estos usuarios. Vacío significa cualquiera.
• Relationship to the repository: solo los autores con esa relación con el repositorio (owner, member, collaborator, contributor, first time contributor, first timer, none). Ninguna marcada significa cualquiera.
• Ignore bots: descarta los eventos enviados por cuentas bot.

Puedes cambiarlo después con Change en el trigger.

Qué recibe el agente

El evento le llega al agente como datos, después de tus instrucciones y claramente marcado como algo que viene de fuera. Nunca se toma como instrucciones.

• Los eventos de GitHub de pull requests, issues y ejecuciones de workflow llegan recortados a los campos que importan, con las cadenas largas cortadas con una marca:
  • Pull requests: el repositorio, el número, el título, el cuerpo (hasta 8 KiB), el autor y su relación con el repositorio, las ramas y el commit, el enlace y cuántos archivos han cambiado.
  • Issues: el repositorio, el número, el título, el cuerpo (hasta 8 KiB), el autor, las etiquetas y el enlace.
  • Ejecuciones de workflow: el repositorio, el workflow, la ejecución, la rama y el commit, el enlace y las pull requests relacionadas.
• Cualquier otro evento (otros eventos de GitHub, Stripe, NaN) llega como su cuerpo JSON, si ocupa como mucho 48 KiB y tiene 8 niveles de anidamiento como mucho. Si no, aparece como Too large y no arranca ningún run.

Los cuerpos de los webhooks tienen un tope de 1 MiB.

Qué recibe el emisor de vuelta

Un 200 es definitivo: el emisor no debería reintentarlo. Un 429, 500 o 503 no se registra, así que un reintento o un reenvío se procesa como nuevo.

Entregas

La pestaña Deliveries lista los últimos 50 webhooks que ha recibido la automatización en los últimos 30 días (hasta 100 con --limit en la CLI o limit en la API), del más reciente al más antiguo, con cuándo llegó, su id de entrega, qué pasó y el run que lanzó:

No se guarda ningún payload ni ninguna cabecera. Las entregas con una firma incorrecta nunca se guardan, y las limitadas (límite de peticiones, cola llena, no disponible temporalmente) se responden pidiendo un reintento y no se listan.

Desde la terminal: nan automations deliveries <automation>. Desde la API: GET /v1/automations/{id}/deliveries.

Rota la URL o el secreto

Rotate, en un webhook, te da credenciales nuevas. Marca qué reemplazar:

• New webhook URL: la URL actual deja de funcionar al momento.
• New signing secret (marcado por defecto): por defecto, el secreto anterior sigue funcionando 24 horas, para que puedas actualizar el emisor sin perder eventos. Desmarca Keep the old secret valid for 24 hours si el anterior se ha filtrado: deja de funcionar al momento. Para Stripe, rota antes el secreto en Stripe y pega el nuevo whsec_....

Los valores nuevos se muestran una sola vez, como cuando añadiste el webhook.

Bucles

Una automatización que comenta en una pull request puede recibir un webhook por su propio comentario, y una automatización que hace push puede disparar el CI que a su vez la vuelve a lanzar. NaN para esos bucles:

• Todo lo que hace un run lleva su marca: una línea Nan-Run: en los commits que sube, una marca oculta en comentarios, reviews y pull requests, y las ramas nan-run/... en las que trabajan los runs (un evento en una rama con otro nombre se reconoce por las demás marcas). Tus propios scripts pueden reenviar NAN_RUN_ID como X-Nan-Run-Id.
• Un run lanzado por un webhook o una programación está en la profundidad 1, y un evento causado por un run está un nivel más abajo que ese run. Por encima de la Chain depth de la automatización (2 por defecto, de 0 a 5) se para y aparece como Stopped: caused by one of its own runs. Con 2, un run de un webhook puede lanzar un run más, no dos.

Los runs por hora de cada automatización, los 120 runs por hora desde webhooks y programaciones entre todas tus automatizaciones, y Skip the new event paran un bucle que se cuele entre las marcas.

Programaciones

Añade una programación

En la pestaña Triggers, pulsa + Schedule:

• Schedule (cron): cinco campos, minuto, hora, día del mes, mes y día de la semana. Por ejemplo 0 9 * * 1-5 (días laborables a las 9:00) o 30 */2 * * * (cada dos horas, a y media). También funcionan los atajos @hourly, @daily, @weekly, @monthly y @yearly.
• Time zone: la zona horaria; las horas la siguen. Empieza con la de tu navegador.

El portal te enseña las próximas ejecuciones antes de guardar. Pulsa Add schedule.

Reglas

• Al menos 15 minutos entre runs. Una programación cuyas próximas ejecuciones estén más juntas se rechaza.
• Hasta 10 programaciones entre todas tus automatizaciones.
• Cambios de hora: cuando se adelantan los relojes, la hora que se salta se ejecuta en la siguiente hora válida; cuando se atrasan, la hora repetida se ejecuta una vez.
• Unos segundos después del minuto: cada programación se dispara hasta un minuto después de su hora, siempre con el mismo desfase, para que las programaciones en punto no arranquen todas a la vez.
• No se recupera lo perdido: si un run no pudo arrancar a su hora (durante un mantenimiento, por ejemplo), aún arranca si llega como mucho 15 minutos tarde. Más tarde que eso, esa hora se salta y nunca se recupera.

Última ejecución

Cada programación muestra su próxima ejecución y cómo fue la última:

Un run programado recibe, como datos, la hora para la que estaba programado, la expresión cron y la zona horaria: scheduled_for, cron y timezone.

Preguntas frecuentes