Un webhook es una URL de tu servidor a la que llamamos cuando pasa algo, por ejemplo cuando una pregunta recibe todas sus respuestas. Así tu código no tiene que preguntar una y otra vez.

Configurar uno

  1. En Desarrolladores, elige Webhooks y añade un endpoint.
  2. Escribe una URL HTTPS y elige los eventos que quieras, por ejemplo question.completed.
  3. Copia el secreto de firma. Se muestra una sola vez.
  4. Envía una prueba para comprobar que tu servidor la recibe y que la firma es válida.

También puedes gestionar los endpoints desde tu código: consulta la última sección.

Eventos

Preguntas reservadas, completadas, incompletas, canceladas o rechazadas; créditos comprados, escasos o a punto de caducar; reclamaciones resueltas; y una conexión cerca de su tope. Una prueba que envíes llega como webhook.test. Para actuar sobre estos eventos sin un servidor, usa la app de Zapier.

Cada endpoint conserva la versión del contenido con la que se creó. Dentro de una versión solo añadimos campos; nunca quitamos ni cambiamos ninguno. La documentación de webhooks (en inglés) enlaza los campos exactos de cada evento.

Webhooks de un equipo

Un endpoint pertenece a la cuenta en la que lo creaste. Si lo creas mientras trabajas en un equipo, recibe los eventos de las preguntas de todos los miembros de ese equipo y de los créditos del equipo. Quien hizo la pregunta también recibe el evento en sus propios endpoints.

En un equipo, el propietario y los administradores pueden añadir, cambiar y eliminar endpoints. Los miembros pueden verlos, junto con sus envíos.

Solo algunas preguntas

Puedes dar un filtro a un endpoint para que solo reciba los eventos de preguntas de los proyectos o etiquetas que elijas. Los eventos que no tratan de una pregunta, como los créditos escasos, llegan siempre.

Comprobar la firma

Cada envío va firmado con tu secreto de dos formas, así que puedes comprobar la que mejor te venga:

  • las cabeceras webhook-id, webhook-timestamp y webhook-signature de Standard Webhooks, que muchas bibliotecas de webhooks comprueban por ti;
  • nuestra cabecera x-50heads-signature, con una marca de tiempo y un HMAC-SHA256 del cuerpo.

Comprueba una de las dos antes de fiarte del contenido. La documentación de webhooks (en inglés) tiene código para copiar en TypeScript, Python y Go.

Si tu secreto se creó antes del 10 de octubre de 2026 y usas una biblioteca de Standard Webhooks, rota el secreto una vez para que la biblioteca lo acepte.

Cambiar el secreto

Al rotarlo recibes un secreto nuevo, que se muestra una sola vez. El anterior sigue funcionando a su lado durante 24 horas, salvo que elijas otro plazo, de hasta 7 días. Mientras tanto, cada envío va firmado con los dos, así que nada falla mientras actualizas tu servidor.

Si crees que un secreto se ha filtrado, rótalo sin solapamiento. El secreto anterior deja de funcionar al momento.

Reintentos y reenvío

Responde con un estado 2xx en menos de diez segundos. Si no, reintentamos con esperas crecientes, ocho veces a lo largo de unas 24 horas. El registro Envíos muestra cada intento, y puedes repetir cualquier envío.

A veces un envío llega dos veces o desordenado. Usa el id del evento para ignorar los repetidos.

Si cinco envíos seguidos fallan tras todos los reintentos, desactivamos el endpoint y te avisamos por correo. El correo enlaza con el endpoint en Webhooks, dentro de Desarrolladores. Aparece como Desactivado, con cuándo se desactivó y por qué. Cuando tu servidor funcione, elige Reanudar y reenvía los envíos que te perdiste. No se envía nada a un endpoint mientras está desactivado.

También puedes elegir Pausar en cualquier endpoint para detener los envíos un tiempo. Aparece como desactivado del mismo modo, y Reanudar lo pone en marcha otra vez. Solo el propietario o un administrador puede pausar o reanudar el endpoint de un equipo.

Gestionar webhooks desde tu código

Una clave, o un asistente de IA que hayas conectado, puede listar, añadir, cambiar, probar y reenviar endpoints si tiene estos permisos:

  • webhooks:read: ver los endpoints y sus envíos.
  • webhooks:write: añadir, cambiar, rotar el secreto, probar, reenviar y eliminar endpoints.

Nunca se conceden por defecto, porque deciden adónde se envían los eventos de tus preguntas. Márcalos al crear una clave. Una aplicación tiene que pedirlos, y los ves en la lista antes de aprobarla. Las claves creadas antes de que existieran los permisos no pueden gestionar webhooks: crea una clave nueva. La documentación de webhooks (en inglés) tiene los detalles.