Webhook para Zapier y Make

Por qué un webhook y no una aplicación lista en Zapier

Hasta abril de 2024 existía una vía oficial: Facebook Groups API, en la que se basaban el disparador «New Post in Group» de Zapier y el módulo correspondiente de Make. Meta la desactivó y no puso nada a cambio. La aplicación de Facebook en Zapier sigue existiendo, pero admite páginas y anuncios: los grupos desaparecieron de la lista de disparadores y no volverán, porque ya no existe una interfaz en la que puedan funcionar.

LeadScanner lee grupos públicos y fanpages sin cuenta, tal como los ve una persona sin iniciar sesión, y después de cada escaneo puede enviar un evento a la dirección indicada. Para Zapier y Make es un webhook entrante normal: exactamente el disparador que falta. Después queda todo lo que estas herramientas hacen bien: una fila en una hoja de cálculo, una tarjeta en el CRM, un mensaje en Slack, una tarea para el vendedor.

El canal webhook está disponible en el plan Growth y superiores. Lo configura el propietario o administrador de la organización, en el panel, en Notificaciones → Canales.

Configuración en Zapier

En Zapier, crea un nuevo Zap y selecciona como disparador la aplicación «Webhooks by Zapier» y el evento «Catch Hook». Zapier mostrará la dirección en la que escucha: cópiala. No cierres esta pestaña, volverás a ella en un momento.

En el panel de LeadScanner, abre Notificaciones → Canales y añade un canal Webhook. Pega la dirección copiada. Si quieres que del otro lado puedan distinguir tus eventos de los ajenos, añade un encabezado de autenticación: un nombre (por ejemplo, X-Api-Key) y un valor que inventes tú. Es opcional, pero económico, y vale la pena hacerlo de inmediato.

Selecciona los eventos que deben enviarse: «Nuevos leads», «Escaneo finalizado» o ambos. Para la automatización de ventas suele bastar el primero; el segundo sirve si quieres registrar cada escaneo, incluso uno vacío. Guarda el canal y haz clic en «Enviar prueba».

Vuelve a Zapier y haz clic en «Test trigger». Zapier recibirá el evento de prueba y lo desglosará en campos que desde ahora puedes mapear en los siguientes pasos: person_name a la columna de apellido, post_url al enlace, score a la prioridad. El evento de prueba tiene el campo test configurado en true y datos de ejemplo: no añadas a esta persona al CRM, porque no existe.

Configuración en Make

En Make, añade al escenario el módulo «Webhooks» → «Custom webhook», ponle un nombre y copia la dirección generada. Desde ese momento Make escucha y espera el primer mensaje para leer de él la estructura de datos.

Los pasos en el panel de LeadScanner son los mismos que para Zapier: Notificaciones → Canales → Webhook, pega la dirección, añade opcionalmente un encabezado de autenticación, elige los eventos, guarda y haz clic en «Enviar prueba».

Después de la prueba, Make mostrará que reconoció la estructura. Si no lo ves —por ejemplo, porque el webhook ya estaba escuchando y guardó otra estructura— haz clic en «Redetermine data structure» en el módulo y envía la prueba una vez más. Desde ese momento, los campos de la carga están disponibles en cada módulo posterior del escenario.

Una nota práctica para ambas herramientas: el evento «Nuevos leads» lleva una lista, no un solo lead. En Make, divídela con un iterador; en Zapier, usa el paso «Looping by Zapier»; o mapea solo el primer elemento si de todos modos reaccionas a todo el lote a la vez.

Evento new_leads: qué recibes

Cada evento es una solicitud POST con cuerpo en formato JSON. Arriba siempre está el mismo conjunto de campos: event — nombre del evento, aquí new_leads; version — número de versión del formato, hoy 1; organization_id — identificador de tu organización; sent_at — hora de envío en ISO 8601; subject — título de una frase, el mismo que va en el asunto del e-mail; leads_count — número de leads en el lote; leads — lista de leads.

Cada elemento de la lista leads incluye: person_name — nombre y apellido del autor de la publicación, tal como aparece en Facebook; score — puntuación de 0 a 100, cuanto más alta, más segura la consulta; excerpt — fragmento de la publicación o comentario donde se hizo la pregunta; post_url — enlace a la publicación; profile_url — enlace al perfil del autor, si era visible; de lo contrario null; rationale — una frase sobre por qué esta publicación se consideró un lead; source_name — nombre del grupo o página donde apareció.

El envío de prueba tiene exactamente esta estructura, solo con datos de ejemplo y un campo adicional test configurado en true. Es la forma más sencilla de ver un ejemplo completo: haz clic en «Enviar prueba» y revisa en Zapier o Make lo que llegó.

Evento scan_finished: lo mismo más el escaneo

El evento scan_finished incluye todos los campos descritos arriba —con la lista de leads encontrados en este escaneo, que puede estar vacía— y además el objeto scan. Dentro: id —identificador del escaneo; source_id, source_name y source_url —qué fuente se revisó; status —cómo terminó; mode —modo, palabras clave o IA; scheduled_slot —franja del calendario a la que pertenecía el escaneo; started_at y finished_at —hora de inicio y fin; points_spent —cuántos puntos costó; leads_found —cuántos leads encontró; error y error_code —descripción y código del error cuando el escaneo falló; de lo contrario, null.

También incluye coverage, es decir, el recuento de lo que revisó el escaneo: posts_seen y comments_seen —cuántas publicaciones y comentarios leyó; posts_suppressed —cuántas publicaciones omitió porque sus autores solicitaron eliminar sus datos; posts_stale y comments_stale —cuántos eran más antiguos que la ventana de actualidad; posts_unchanged y comments_unchanged —cuántos ya conocía de una revisión anterior y no volvió a evaluar; graded —cuántos fragmentos se evaluaron; leads —cuántos de ellos se convirtieron en leads; rejected —lista de pares reason y count, es decir, por qué motivos y cuántos se descartaron.

Los números de coverage siempre cuadran: graded son las publicaciones y comentarios recientes tras restar los antiguos y ya conocidos, y leads más la suma de rejected da graded. Si creas un dashboard con esto, puedes confiar en estas dos identidades.

Los motivos de rejected siempre son de la misma lista: no_keyword (no apareció ninguna palabra clave), no_intent (no se puede determinar si el autor busca algo), not_in_market (habla el lenguaje del sector, pero no compra: aconseja, relata, vende), outside_offer (compra, pero no lo que ofreces o no donde operas), excluded (pregunta exactamente por lo que no haces), below_threshold (encaja, pero demasiado poco para el umbral), ungraded (el modelo respondió en un formato que no se pudo leer). Guárdalos como diccionario, no los mapees a ojo.

Firma HMAC y qué usar en su lugar

Si configuras un secreto en el canal, cada solicitud recibirá dos encabezados: X-LeadScanner-Timestamp con la hora de la firma en segundos Unix y X-LeadScanner-Signature con el valor v1=<hex>, donde hex es el HMAC-SHA256 de la cadena «<timestamp>.<ciało>» calculado con tu secreto. El receptor calcula lo mismo de su lado y compara; rechaza una firma con más de cinco minutos. Así, nadie que solo conozca la dirección podrá hacerse pasar por LeadScanner ni reproducir una solicitud interceptada una semana después.

Sin secreto no hay encabezados de firma: el evento se envía sin firma, como en la mayoría de integraciones no-code. Zapier y Make no calculan HMAC sin un paso adicional de código, así que para ellos una protección más simple y suficiente es el encabezado de autenticación del panel: del lado de la automatización, añade un filtro que solo deje pasar solicitudes con ese nombre y ese valor.

Hay dos reglas que no se pueden desactivar: la dirección debe ser HTTPS pública —http normal o una dirección de red local no funcionarán— y se rechazan las redirecciones. Si tu servidor responde 301 o 302, la entrega termina con error, no continúa silenciosamente a otra dirección, porque en esa otra dirección la firma y el encabezado de autenticación llegarían a donde no deben.

Cuando falla la entrega

Una respuesta distinta de 2xx, un tiempo de espera agotado o una conexión interrumpida indican un intento fallido. No termina ahí: reenviamos el evento tres veces, con intervalos crecientes —el primer reintento tras medio minuto y el último tras unos minutos—. Basta para esperar un reinicio del servidor o un límite momentáneo de Zapier, y al mismo tiempo la notificación que finalmente llegue seguirá siendo una notificación, no una crónica.

Cada intento —exitoso o no— es visible en el panel, debajo del canal, con la hora, el código de respuesta y el motivo del error. Si el evento no llega tras cuatro intentos, queda en esta lista como fallido y ahí debes empezar a buscar: normalmente se trata de una dirección de Zapier que dejó de existir o de un escenario de Make que alguien desactivó.