Integración de webhooks entrantes

Se necesita ayuda del desarrollador

Necesitará la ayuda de su equipo de desarrollo para configurar la integración. Por favor, comparta esta guía con ellos.

Los webhooks entrantes permiten que los servicios de terceros envíen eventos directamente a Pushwoosh. Cuando un servicio de terceros activa un webhook, Pushwoosh autentica la solicitud, identifica al usuario y aplica el mapeo que usted configuró: rellenar etiquetas en el perfil del usuario, disparar un evento de Pushwoosh, o ambos. Un evento disparado puede entonces iniciar o avanzar un journey.

Utilice webhooks entrantes para conectar herramientas como CRMs, plataformas de comercio electrónico o servicios de análisis sin construir o mantener su propio servidor.

Si el identificador entrante no coincide con un usuario existente, Pushwoosh puede crear el usuario en lugar de descartar la solicitud. Active la casilla de verificación de creación automática descrita en Mapear datos entrantes.

Antes de empezar

Prepare lo siguiente antes de abrir la configuración del webhook.

1. Decida qué debe hacer el webhook. Un webhook debe mapear al menos una etiqueta, un evento, o ambos. Para disparar un evento, elija uno existente de su proyecto (por ejemplo, CheckoutSuccess) o cree uno con los atributos que desea rellenar a partir de los datos entrantes. Las etiquetas se pueden mapear a etiquetas existentes o crearse en el momento al configurar el webhook.

2. Asegúrese de que su servicio de terceros pueda enviar webhooks. El servicio debe poder enviar una solicitud HTTP POST a una URL externa cuando ocurra el evento que le interesa, por ejemplo, un nuevo pedido o el envío de un formulario.

3. Obtenga un payload JSON de muestra de su servicio de terceros. Este es un pequeño ejemplo de los datos que el servicio envía en cada evento. Lo necesitará para mapear los campos del payload a las etiquetas y atributos del evento.

Crear un webhook

Abrir la configuración del webhook

1. En su cuenta de Pushwoosh, vaya a Settings → Integrations → Inbound webhooks y haga clic en Settings.

2. Haga clic en Create webhook para abrir la pantalla de configuración: Paste a sample payload a la izquierda, Webhook setup a la derecha.

3. Ingrese un nombre para el webhook para que pueda identificarlo en la lista más tarde.

Mapear datos entrantes

1. En Paste a sample payload, pegue un payload JSON de muestra de su servicio de terceros. Pushwoosh extrae los campos y los carga en los menús desplegables de campos de payload.

Nota

Si actualiza el payload más tarde, haga clic en Reload select options para actualizar los menús desplegables. Esto restablecerá su mapeo de campos actual. Necesitará volver a mapear sus campos.

Payload de muestra:

{
  "id": "12345",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "loyalty_tier": "gold",
  "order_number": "ORD-001",
  "price": 99.99
}

2. En Identify users by, elija cómo Pushwoosh debe hacer coincidir la solicitud entrante con un usuario:

• User ID: su identificador interno asignado a un usuario en el sistema.
• Email: coincide por dirección de correo electrónico.
• Phone: coincide por número de teléfono.
• HWID: un identificador de dispositivo, navegador o correo electrónico.
• Token: coincide por un token push de dispositivo.

3. En Payload field, seleccione el campo que contiene el valor coincidente.

4. Opcional: active la casilla de verificación debajo de Payload field para crear un nuevo usuario automáticamente cuando no se encuentre ninguna coincidencia, en lugar de descartar la solicitud. Su etiqueta coincide con su elección de identificador, por ejemplo Create a new User ID if no match is found o Create a new Email if no match is found. La casilla de verificación está deshabilitada para HWID y Token, porque Pushwoosh no puede crear un identificador de dispositivo, navegador o token push antes de una sesión de SDK real.

Cada webhook debe mapear al menos una etiqueta, disparar un evento, o ambos.

Añadir etiquetas al perfil

Use Add tags to profile para guardar los valores del payload como etiquetas en el perfil del usuario coincidente. Rellene los datos del perfil como el nivel del plan o la ciudad para una mejor segmentación.

1. Haga clic en + Add tag.
2. En Tag name, elija una etiqueta existente de la lista, o escriba un nuevo nombre. Pushwoosh muestra Create: <name> para confirmar que creará una.
3. Si eligió una etiqueta existente, Type muestra su tipo y no se puede cambiar. Si creó una nueva etiqueta, abra Type y elija su tipo de datos. Pushwoosh la guarda como una etiqueta específica del usuario de este tipo.
4. En Payload field, seleccione el campo de su payload de muestra que contiene el valor.
5. Repita los pasos 1–4 para cada etiqueta que desee rellenar.

Para eliminar una fila, haga clic en ×.

Registrar un evento

Use Record an event para disparar un evento de Pushwoosh cuando el webhook reciba una solicitud válida. Un evento disparado puede iniciar o avanzar un journey.

1. En Event, seleccione el evento de Pushwoosh a disparar.
2. Haga clic en + Add attribute.
3. En Event attribute, elija un atributo existente del evento seleccionado de la lista, o escriba un nuevo nombre. Pushwoosh muestra Create: <name> para confirmar que creará uno.
4. Si eligió un atributo existente, Type muestra su tipo y no se puede cambiar. Si creó un nuevo atributo, abra Type y elija su tipo de datos.
5. En Payload field, seleccione el campo de su payload de muestra que contiene el valor.
6. Repita los pasos 2–5 para cada atributo que desee rellenar.

Para eliminar una fila, haga clic en ×.

Habilitar y conectar

1. Cuando la configuración esté completa, haga clic en Enable webhook. Se abrirá la ventana Webhook URL.

Se necesita ayuda del desarrollador

Los siguientes pasos requieren acceso a la configuración de webhooks de su servicio de terceros. Comparta la URL y el Secreto con su equipo de desarrollo.

2. Copie la URL y establézcala como el destino del webhook en su servicio de terceros.

3. Copie el Secret y péguelo en su servicio de terceros como el valor del encabezado Authorization. El valor incluye el prefijo Bearer, así que úselo tal cual. Pushwoosh rechaza cualquier solicitud en la que este encabezado falte o no coincida.

4. Haga clic en Copy en el bloque Example request para copiar una solicitud POST de muestra. Úsela para enviar una solicitud de prueba y confirmar que Pushwoosh acepta el webhook, o compártala con su equipo como una plantilla para la integración.

Después de habilitar el webhook, aparece en la lista de Webhooks con un estado habilitado y comienza a aceptar solicitudes.

Lista de webhooks

La lista de webhooks entrantes muestra todos los webhooks de su proyecto.

Cada fila muestra:

• Name: nombre del webhook.
• Status: Enabled o Disabled.
• Received: número total de solicitudes entrantes recibidas por el webhook.
• Last modified: cuándo se modificó el webhook por última vez.

Gestionar webhooks

Abra el menú de la fila para:

• Edit settings: abre la configuración del webhook para que pueda cambiar el nombre, el evento, el mapeo de campos y la identificación del usuario.
• Copy URL: abre la ventana Webhook URL con la URL y el Secret para que pueda copiarlos de nuevo.
• Activity log: abre el registro de solicitudes para este webhook.
• Delete: elimina el webhook de la lista.

Para un webhook habilitado, haga clic en Disable para desactivarlo sin eliminar la configuración. Para un webhook deshabilitado, haga clic en Enable para comenzar a aceptar solicitudes nuevamente.

Ver el registro de actividad

El registro de actividad muestra todas las solicitudes entrantes para el webhook seleccionado.

Panel de resumen

En la parte superior, revise el resumen de las últimas 24 horas:

• Total hits: número total de solicitudes entrantes recibidas.
• Warning: solicitudes en las que el usuario fue identificado (o creado) pero al menos un mapeo de etiqueta o evento configurado no se pudo aplicar.
• Failed: solicitudes que no se procesaron en absoluto, por ejemplo, debido a un secreto incorrecto o a un campo de identificador faltante. Una solicitud fallida no detiene el webhook. Pushwoosh continúa aceptando y procesando solicitudes posteriores.

Motivo del fallo	Qué significa
Auth rejected	El secreto compartido no coincide con la configuración del webhook. Si cinco solicitudes consecutivas fallan con este error, Pushwoosh le enviará una notificación. Actualice el secreto para reanudar. No se necesita reactivación.
User identifier field missing	El campo del payload mapeado para la identificación del usuario no está presente en la solicitud.

Entradas de solicitud

Cada entrada muestra un icono de estado, el identificador de usuario (por ejemplo, User ID o Email), la marca de tiempo de la solicitud y una marca de verificación para cada capacidad que configuró en el webhook: User ID (o su identificador elegido), Tags y Event. Una marca de verificación significa que esa parte de la solicitud se aplicó con éxito; una solicitud puede mostrar una mezcla de elementos verificados y fallidos. Haga clic en Show para expandir el payload JSON completo recibido.

Ver eventos y etiquetas disparados por webhooks en el User Explorer

Cuando una solicitud de webhook se procesa con éxito, Pushwoosh registra el resultado en el usuario coincidente (o recién creado) en el User Explorer. Dónde aparece el evento depende de cómo identificó al usuario:

• User ID, Email o Phone: el evento se registra en el perfil del usuario. Abra el usuario y vaya a Events history.
• HWID: el evento se registra en el dispositivo coincidente. Abra el usuario, encuentre el dispositivo en Active user devices y vaya a su pestaña Events history.

Encuentre el evento por nombre y expándalo para ver los atributos mapeados (por ejemplo, price o products) y el atributo __webhook con el ID del webhook. Las etiquetas mapeadas aparecen en el mismo usuario, en la pestaña User overview, independientemente del tipo de identificador.

Usar webhooks entrantes con journeys

Después de que un webhook esté habilitado y dispare eventos con éxito, use el evento seleccionado como una entrada de journey basada en disparadores. Cuando el webhook recibe una solicitud válida, Pushwoosh dispara el evento mapeado. Cualquier journey que utilice este evento como disparador de entrada se iniciará automáticamente para el usuario coincidente.