(Entrega de webhooks · Nautilus)
Tu producto publica un evento con una llamada a la API. Nautilus lo pone en cola, lo firma y lo entrega a cada endpoint suscrito a ese tipo de evento. Una entrega fallida se reintenta con un calendario fijo, y cada intento aparece en tu panel con la respuesta que obtuvo.
curl -X POST https://api.vernesoft.com/v1/relay/messages \
-H "Authorization: Bearer vrn_relay_•••" \
-d '{"event_type":"user.created","payload":{"id":"usr_123"}}'(Construir o comprar)
La primera versión es una petición POST en un bucle de reintentos. Deja de ser simple cuando el servidor de un cliente cae durante un fin de semana, cuando un despliegue de un manejador sale roto y hay que reenviar una hora de eventos, y cuando un endpoint lento empieza a retrasar a todos los demás.
Construirlo tú mismo
Entrega de webhooks en Nautilus
(Funcionalidades principales)
(01)
Una respuesta distinta de 2xx, o un timeout, cuenta como intento fallido. El mensaje se reintenta con intervalos crecientes: 8 intentos en unas 28 horas, el mismo calendario para cada endpoint. La entrega es al menos una vez, así que un reintento puede llegar al servidor de tu cliente más de una vez.
(02)
Cada mensaje se firma con HMAC SHA-256, con un secreto que pertenece a un endpoint. Cada entrega lleva tres cabeceras (svix-id, svix-timestamp y svix-signature), y la firma cubre el id, la marca de tiempo y el cuerpo, de modo que tus clientes pueden comprobar quién lo envió y rechazar una petición repetida.
(03)
Publicar un evento devuelve 202 en cuanto el mensaje está en cola. La entrega a los servidores de tus clientes ocurre después, así que un endpoint lento o caído no retrasa la petición que tu propio código está esperando.
(04)
Publica un evento, por ejemplo user.created, y se entrega a cada endpoint suscrito a ese tipo de evento. Añade un canal a un mensaje para llegar solo a los endpoints que lo escuchan.
(05)
Cada intento queda registrado con su hora, el código de respuesta y el cuerpo de la respuesta que devolvió tu servidor, para ver por qué falló una entrega. En la pestaña Events de tu panel puedes reenviar una entrega, o repetir todo lo que falló desde el momento que elijas, hasta 14 días atrás.
(06)
Envía una idempotency_key y una llamada repetida devuelve el mensaje original en lugar de crear un segundo. La entrega en sí es al menos una vez: un reintento puede volver a llegar a tus clientes, así que deben deduplicar por la cabecera svix-id, que es la misma en cada intento de un mismo mensaje.
(Parte de Nautilus)
La entrega de webhooks es una parte de Nautilus, no un servicio aparte. Comparte cuenta y panel con el inicio de sesión y las tareas cron. Los eventos de inicio de sesión, como un registro nuevo, llegan a tu backend de la misma forma, como webhooks firmados y reintentados.
(Experiencia del desarrollador)
Publica un evento con una sola llamada: mediante un SDK oficial para Node, Python, PHP o Rust, o con una petición HTTP simple si prefieres no añadir dependencias.
curl -X POST https://api.vernesoft.com/v1/relay/messages \
-H "Authorization: Bearer $VERNE_RELAY_KEY" \
-H "Content-Type: application/json" \
-d '{
"event_type": "subscription.renewed",
"payload": { "user_id": "usr_987", "plan": "pro_tier" },
"idempotency_key": "evt_5f3c9a"
}'(FAQ)
Nautilus genera un secreto único para cada endpoint y firma cada petición saliente con HMAC SHA-256. Cada entrega lleva tres cabeceras: svix-id, svix-timestamp y svix-signature. La firma se calcula sobre svix-id, svix-timestamp y el cuerpo en bruto, unidos por puntos, de modo que quien lo recibe puede verificar la autenticidad y rechazar una repetición. Las bibliotecas oficiales de Svix lo comprueban todo con una llamada.
Cualquier respuesta distinta de 2xx, y cualquier timeout, cuenta como intento fallido. El mensaje se reintenta con un calendario fijo de intervalos crecientes: 8 intentos en unas 28 horas, lo que evita saturar servidores que aún se están recuperando. El calendario es el mismo para todos los endpoints y no se puede cambiar. Un endpoint que falla todos los intentos durante cinco días se desactiva, y nada te avisa, así que echa un vistazo a la pestaña Events de vez en cuando. Cuando tu servidor vuelva, puedes reenviar las entregas fallidas desde el panel, o repetir todo lo que falló desde el momento que elijas.
Sí. Expón tu endpoint local con un túnel como ngrok o Cloudflare Tunnel y añade esa URL como endpoint en el panel. Usa una clave live: los eventos enviados con una clave de prueba se aceptan pero no se entregan. El registro de entregas te permite inspeccionar cada intento mientras pruebas.
Puedes, y es mucho más que un POST: una cola y backoff exponencial, secretos por endpoint y firma HMAC, una forma de deduplicar un envío reintentado y un registro de entregas que tu equipo de soporte pueda consultar cuando un cliente dice que el evento nunca llegó. Nautilus tiene esa lista ya construida, y pagas por solicitud de API. Lo que cedes es control: el calendario de reintentos es fijo, los endpoints se añaden desde el panel y no por la API, y el motor de debajo es Svix, que es de código abierto si alguna vez necesitas ejecutarlo tú mismo.
Hoy no por la API. Los endpoints se crean en el panel, así que si quieres que tus clientes peguen su propia URL en los ajustes de tu producto, esa pantalla te toca construirla a ti, y por ahora alguien con acceso al panel añade la URL. Publicar eventos y leerlos de vuelta está disponible por la API.
(Empieza)
La entrega de webhooks es una parte de Nautilus: la misma cuenta y el mismo panel que el inicio de sesión y las tareas cron.
Lo que cuesta construirlo
Construirlo no es la parte cara. Una cola, un reintento con backoff y un ayudante de firma son una semana de trabajo, y la mayoría de los equipos llegan ahí sin problema. El gasto empieza la semana siguiente, cuando un cliente dice que un evento nunca llegó y responder a eso significa leer logs a mano. Y no se acaba, porque cada nuevo endpoint de cliente es una nueva forma de fallar en la entrega.
Además gasta tu atención donde no rinde nada. Nadie eligió tu producto porque tus reintentos usen backoff exponencial. Pero un webhook que dejó de llegar en silencio es primero un ticket de soporte, luego una conversación sobre un reembolso y a veces un cliente que se va. Mucha consecuencia y ningún mérito: exactamente la forma de algo que conviene comprar en lugar de construir.
Si prefieres construirlo, constrúyelo: el diseño no es ningún secreto y tomaríamos casi las mismas decisiones. Solo calcula su coste como un servicio que operarás durante años, no como un sprint. Si prefieres no hacerlo, un endpoint que ya tienes puede recibir entregas firmadas y reintentadas en cuanto tengas una clave de API y su URL esté en el panel, y las primeras 3.000 solicitudes de cada mes son gratis.