Webhooks: convierte en nota todo lo que hable HTTP

Cada espacio de trabajo ya tenía tres puertas de entrada: la app, la CLI y un asistente de IA por MCP. Las tres dan por hecho que quien escribe es una persona o un asistente. Muchas de las cosas que vale la pena guardar no las escribe ninguno de los dos: un despliegue que falló, un comentario en Figma, el pago semanal, un formulario que alguien envió.

Notez v0.15.0 añade la cuarta puerta: una URL de webhook. Cualquier cosa que pueda enviar una solicitud HTTP ya puede crear una nota.

Una URL, una línea de curl

Crea un webhook en Configuración → Integraciones → Webhooks y Notez te da una URL. Esa es toda la configuración:

curl -X POST "https://api.notez.dev/api/webhooks/notes/<your-token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Deploy failed on main", "content": "## Details\n- commit abc123", "tags": ["alerts"]}'

La nota aparece con sus etiquetas, dentro de la nota que elegiste como destino y en la columna del tablero que indicaste. Las etiquetas que nunca habías usado se crean en el momento.

Los emisores que no van a aprender tu formato

Un JSON bien estructurado funciona cuando controlas al emisor. A GitHub, Stripe y Sentry les da igual qué estructura prefieras: envían su propio payload, y lo único que eliges tú es la URL.

Por eso un webhook tiene dos modos. Formato de Notez valida de forma estricta, rechaza errores de escritura y te da título, contenido, etiquetas y adjuntos. Cualquier JSON acepta lo que llegue y lo guarda como un bloque de código formateado, con el título del payload si trae title y, si no, con el nombre del webhook. Nada se rechaza por traer campos inesperados, y ese es justamente el objetivo.

Adjuntos, también los que solo tienes como enlace

Una solicitud puede llevar hasta diez archivos, de tres maneras: como subida de archivo, como base64 dentro del JSON o como un enlace que Notez descarga por ti. La tercera es la que hace útiles las herramientas de automatización: Zapier te da un enlace a un archivo, nunca los bytes.

Descargar cualquier cosa a la que apunte una URL también es la forma más rápida de abrir un agujero en tu propia infraestructura. Una URL de webhook es pública, así que, sin protección, "descarga este enlace" permitiría a cualquiera apuntar los servidores de Notez a direcciones internas y leer lo que respondiera. Cada descarga resuelve primero la dirección, rechaza los rangos privados, internos y de metadatos de la nube, vuelve a comprobar después de cada redirección y se conecta solo a la dirección que ya comprobó, de modo que una segunda respuesta DNS no puede colar algo interno después de la comprobación. Los archivos demasiado lentos, demasiado grandes o protegidos por un inicio de sesión se convierten en enlaces dentro de la nota en lugar de desaparecer.

Reintentos, y la nota que no querías tener dos veces

Los emisores reintentan cuando una respuesta tarda demasiado, y un reintento que crea una segunda nota es peor que no tener ninguna. Envía un encabezado Idempotency-Key, o un externalId en el cuerpo, y una repetición dentro de las 24 horas devuelve la nota que ya existe. Notez toma automáticamente el id de entrega de GitHub, así que sus reintentos son seguros sin configurar nada.

Firmas: opcionales a propósito

La URL es la credencial, y las URL se filtran: acaban en logs, en capturas de pantalla, en configuraciones compartidas. Si el emisor sabe firmar sus solicitudes, Notez comprueba la firma y rechaza todo lo demás.

Hice la firma opcional, y eso merece una explicación. La verificación no es un candado que yo controle; es una comprobación de algo que tiene que hacer el emisor. GitHub firma. Stripe firma. Zapier, Atajos y la mayoría de los scripts no pueden. Exigir firmas habría convertido una función que sirve con cualquier cosa en una que sirve con tres servicios, así que la URL sigue siendo la base y la firma es una segunda capa para los emisores que la admiten. La lista marca los webhooks sin firma para que esa concesión siga a la vista y no caiga en el olvido.

Un secreto de firma es una de las pocas credenciales que Notez tiene que poder volver a leer: verificar una firma implica volver a calcularla, así que el secreto se cifra en lugar de guardarse como hash. Esa diferencia importa más de lo que parece, y cambió otra cosa en esta versión.

De paso: las claves ahora se guardan con hash

Las URL de webhook se guardan como hashes, porque para reconocer un token nunca hace falta reproducirlo. Las claves MCP y CLI, cuyo código escribí antes, se guardaban en texto plano: cualquiera que pudiera leer la base de datos podía leerlas.

Ahora también se guardan con hash. El efecto práctico: una clave MCP se muestra una sola vez, al generarla, y después la pantalla solo enseña sus primeros caracteres. Si la pierdes, rótala. La CLI nunca mostraba su clave de todos modos.

Del mismo trabajo salieron dos cambios más pequeños. Cada webhook crea notas en nombre de quien lo configuró, así que al quitar a alguien de un espacio de trabajo ahora se eliminan también sus webhooks: ninguna URL sobrevive a su dueño. Y el registro de auditoría, que guarda los datos de entrada de cada cambio, ahora oculta todo lo que parezca una credencial: estaba a punto de guardar los secretos de firma en texto plano justo al lado de sus copias cifradas.

A qué conectarlo

• GitHub — issues, despliegues, workflows que fallan, con la comprobación de firma activada.

• Zapier o Make — un paso al final de cualquier automatización, que deja el resultado donde lo vas a encontrar.

• Cron y CI — informes nocturnos de copias de seguridad, notas de versión, un resumen que de otro modo se quedaría en un log que nadie abre.

• Tu propia app — solicitudes de soporte, registros de usuarios, cualquier cosa que valga la pena tener junto a tus notas.

Las notas que llegan por webhook llevan la insignia WH, así que lo que escribes tú nunca se pierde entre ellas.

Todos los detalles, los límites y el paso a paso para GitHub están en el artículo de ayuda sobre webhooks.

Sigue leyendo

• Primeros pasos con Notez CLI — los comandos de instalación para macOS, Linux y Windows, dónde guarda la clave notez login y cómo usar la CLI en scripts con --json.

• Cómo crear un sistema para tomar notas si eres desarrollador — cuatro tipos de notas que vale la pena guardar, capturas en menos de cinco segundos, cero carpetas y una revisión semanal de diez minutos.

• Cómo tomar notas desde la terminal — tres formas de tomar notas en la shell, desde echo >> ~/notes.md hasta una CLI de captura, y dónde falla cada una cuando necesitas recuperar la nota.