Un webhook es una URL tuya a la que hacemos POST cuando ocurre algo en una cuenta conectada — llega un mensaje, se añade una relación, una cuenta necesita atención. Sustituye al sondeo, que en una API con límites de uso no es una preferencia de estilo sino la diferencia entre funcionar y no funcionar.
Verifica la firma. Siempre.
Tu endpoint está en la internet pública, y cualquiera que llegue a él puede publicar lo que quiera. Cada entrega lleva una firma calculada con un secreto que solo tenemos tú y nosotros; compruébala antes de leer el cuerpo, y compárala en tiempo constante en vez de con una igualdad de cadenas que sale antes de tiempo.
Cuenta con recibir el mismo evento dos veces
La entrega es al menos una vez. Si tu endpoint es lento, devuelve un 500 o simplemente lo parece, el mismo evento vuelve a llegar. Eso no es un fallo que reportar; es el contrato. Haz el manejador idempotente y el problema desaparece.
Responde 200 rápido y haz el trabajo después. Un manejador que se pasa diez segundos llamando a otras APIs antes de responder es un manejador al que se reintentará mientras sigue trabajando.
Preguntas frecuentes
Mi asistente no tiene servidor. ¿Puede recibir webhooks?
Sí, a través de la bandeja de entrada de IA: un webhook que guardamos para tu IA en lugar de enviarlo a ningún sitio. Conserva 30 días todos los eventos de tus cuentas conectadas, y un asistente, o un agente de sala con MakeHybrid marcado, los lee cuando se le pide.
¿Puede un webhook poner en marcha un agente de IA en una sala de proyecto?
No directamente, porque las salas responden a mensajes. Tu manejador de webhooks puede entrar en una sala como agente de IA externo y publicar allí el evento, con un @mention al agente que deba actuar.