Un webhook envía datos a la URL que elijas en el momento en que ocurre algo, por ejemplo, cuando alguien participa en una campaña o gana un premio. Tu desarrollador configura el sistema que los recibe.
Los webhooks forman parte de los planes que incluyen Webhooks & API (Basic y superiores).
¿Webhooks de campaña o webhooks de cuenta?
- Los webhooks de campaña se configuran en el editor de campañas y se activan solo para esa campaña. Tienen los eventos "Every time a lead participates in a campaign" y "When a lead wins a prize", y ofrecen la mayor cantidad de opciones.
- Los webhooks de cuenta se configuran en Settings > Webhooks. Tienen el evento "When a new lead is created": se activa una vez por persona, la primera vez que se agrega a tus leads, sin importar de qué campaña provenga.
Agregar un webhook a una campaña
- Abre la campaña en el editor y ve a Connect > Webhooks.
- Haz clic en Add webhook.
- Ingresa la Payload URL. Debe comenzar con https: "We only support webhooks over HTTPS to ensure that the data sent remains secure."
- Elige el Content type: application/json o application/x-www-form-urlencoded.
- Elige el Method. El formulario comienza en GET, que envía los datos en la URL. Elige POST para enviarlos en el cuerpo, que es lo que espera la mayoría de los sistemas.
- En Authentication (solo para POST), elige Basic Auth si tu URL requiere usuario y contraseña, y completa Username y Password. De lo contrario, deja None.
- Ingresa un Secret para firmar las solicitudes (recomendado). Consulta "Verificar la firma" más abajo.
- Activa Log response body si quieres ver lo que responde tu sistema. "Enable to store the response body for debugging."
- Mantén Active activado. "We will only deliver events if the webhook is active."
- Elige el evento: "Every time a lead participates in a campaign" o "When a lead wins a prize".
- Activa Custom payload si quieres definir los campos tú mismo (consulta más abajo).
- Haz clic en Add webhook. Verás "Webhook added".
El panel Webhooks muestra los webhooks de la campaña con el estado Active o Inactive, y Last delivery failed si la última solicitud falló. Usa Actions para Edit, See deliveries o Delete un webhook. Al editar un webhook, deja Secret en blanco para conservar el que ya tienes.
Agregar un webhook de cuenta
- Ve a Settings > Webhooks (en Developers). Tus webhooks aparecen en My webhooks (o bajo el nombre de cada lista de leads, si tienes varias).
- Haz clic en la tarjeta con el signo más para agregar un webhook. El cuadro de diálogo Add webhook dice "Send a request to an external URL whenever selected events happen."
- Completa Payload URL, Content type ("Select content type of the webhook"), Method y Secret como se indicó arriba.
- En Which events should trigger the webhook?, elige "When a new lead is created".
- Marca "Yes, allow me to specify a customized payload (Advanced users only)" si quieres usar tus propios campos.
- Marca Log response body ("This webhook will log the response body") si lo necesitas, y mantén Active marcado ("We will deliver event details when this hook is triggered").
- Haz clic en Add webhook.
Haz clic en un webhook para modificarlo (Save changes), definir un New secret, abrir Show deliveries o usar Delete webhook ("This action cannot be reverted!").
Qué se envía
De forma predeterminada, el cuerpo incluye un event (el nombre del evento: lead_created_on_campaign, new_campaign_winner o lead_created) y un objeto data:
campaign: elidy elnamede la campaña (webhooks de campaña)lead: los campos del formulario del lead según su clave de campo (por ejemplo,first_name), además deid,phone_numberycreated_atlead.permissions: para cada casilla de consentimiento, si fue aceptada, el texto, la fecha y la dirección IP (webhooks de campaña)participant: elchanneldel que provino la persona y cuándo participó (webhooks de campaña)quiz: las respuestas a las preguntas del quiz con nombre, también con nombres legibles que empiezan con "Simple"prize: elid,name,value,coupon_codedel premio y cuándo se ganó (webhooks de ganadores)
Los valores vacíos se omiten, al igual que los consentimientos no aceptados. Con el método GET, los mismos datos se envían como parámetros de consulta en la URL.
Payload personalizado
Con Custom payload activado, solo se envían los campos que elijas y no hay envoltorio event.
- En Data mapping, haz clic en Add mapping.
- Escribe el Field name que espera tu sistema. Usa letras, números, guiones y guiones bajos.
- Elige el campo de Scratcher que quieres enviar ("Group → Field"), o Custom value y escribe un Value fijo.
- Repite para cada campo. Elimina uno con el ícono de papelera (Remove o Remove data mapping).
Verificar la firma
Si defines un secreto, cada solicitud incluye un encabezado X-Hub-Signature: sha1= seguido de un hash HMAC-SHA1 del payload codificado en JSON (el cuerpo descrito arriba), usando tu secreto como clave. Calcula lo mismo de tu lado y compáralo para asegurarte de que la solicitud provino de Scratcher.
Entregas y reintentos
- Si tu URL no responde o devuelve un error (estado 400 o superior), Scratcher lo vuelve a intentar dos veces: a los 5 segundos y al minuto.
- Las redirecciones no se siguen, así que usa la URL final.
- Abre las entregas (See deliveries en la campaña, Show deliveries en los webhooks de cuenta) para ver cada solicitud y respuesta. Cada entrega muestra su ID, la Request y la Response con su código de estado (y el Response body si lo registras). Usa copy para copiar un payload.
- Activa Show only failed deliveries para ver solo los problemas. En la parte superior se muestra "Failed deliveries in the last 60 days".
- Haz clic en Retry para volver a enviar una entrega: "The webhook is being resent."
- "Webhook delivery logs are retained for 60 days."
Solución de problemas
- "The ... field must use HTTPS.": la Payload URL comienza con http. Usa https.
- Todas las entregas fallan sin respuesta: la URL no es accesible desde internet, por ejemplo, una dirección local o interna. Usa una URL pública.
- Tu sistema no recibe datos: el método es GET, así que los datos están en la URL. Cambia a POST.
- Falta un campo que tu sistema espera: estaba vacío o el consentimiento no fue aceptado. Configura tu sistema para que trate los campos faltantes como vacíos.