Usar Webhooks

El uso de Webhooks se realiza a través de suscripciones. La creación y gestión de estas suscripciones se realiza mediante las APIs de Actito.

Webhooks en tablas de datos

Suscribirse a un Webhook

Repasemos los conceptos necesarios para configurar un webhook relacionado con los datos de sus tablas:

"on"

Este parámetro indica el elemento de Actito que se está escuchando. Este elemento puede ser:

• PROFILE_TABLE: Una tabla de perfiles

• CUSTOM_TABLE: Una tabla personalizada del modelo de datos

El identificador técnico de la tabla (de perfil o personalizada) para la cual desea recibir notificaciones se especifica en el parámetro "onElementId".

"eventType"

Este parámetro indica el tipo de evento que se está escuchando:

• CREATE: Nuevo perfil o nueva fila en una tabla

• DELETE: Eliminación de un perfil o una fila de una tabla

• UPDATE: Modificación de un perfil o una fila en una tabla

• UPDATED_SEGMENT: Cambio en un segmento (solo para tablas de perfiles)

• UPDATED_SUBSCRIPTION: Cambio en una suscripción (solo para tablas de perfiles)

Es necesario crear una suscripción de Webhook para cada tipo de evento del cual desea recibir notificaciones.

Información

Para las tablas personalizadas del modelo en estrella, es necesario especificar los eventos en el archivo JSON de definición de la tabla (en el parámetro "eventToTrigger").
Siempre existe un evento CREATE por defecto en las tablas personalizadas, pero los eventos de UPDATE deben ser definidos (especialmente para definir qué actualizaciones de campos desencadenan un evento).
No dude en contactar a su administrador de cuenta si necesita ayuda para configurar eventos en sus tablas.

"onFields"

El parámetro "onFields" especifica la lista de campos a escuchar para una tabla de perfiles o una tabla de datos. Este parámetro tiene dos funciones:

Por un lado, los campos enumerados aparecerán en el contenido del evento devuelto por el Webhook a la URL especificada.

Por otro lado, estos campos restringen la activación del evento. Solo se tendrán en cuenta los eventos que afecten al menos a uno de los campos enumerados. Dependiendo del tipo de evento, la información puede ser obligatoria o no:

• CREATE: No obligatorio. Si no se menciona nada, se tendrán en cuenta todas las creaciones y solo se enviarán las información técnica a la URL. Si se menciona una lista, por ejemplo ["emailAddress", "gsmNumber"], solo se enviarán a la URL del Webhook las nuevas entradas que tengan un valor para uno de estos dos campos. Solo se pueden escuchar atributos de perfil o campos de tabla personalizada a través de este método, no suscripciones ni segmentaciones.

• DELETE: No obligatorio. Si no se menciona nada, se tendrán en cuenta todas las eliminaciones. Si se menciona una lista, por ejemplo ["emailAddress", "gsmNumber"], solo se enviarán a la URL del Webhook las nuevas entradas que tengan un valor para uno de estos dos campos.

• UPDATE: Obligatorio. Se debe especificar la lista de campos escuchados, por ejemplo ["emailAddress", "gsmNumber"]. Solo se tendrán en cuenta las actualizaciones de entradas en las que se haya modificado el valor de uno de los campos mencionados. Solo se pueden escuchar atributos de perfil o campos de tabla personalizada a través de este método, no suscripciones ni segmentaciones.

• UPDATED_SEGMENT: Obligatorio. Se debe especificar la lista de segmentaciones escuchadas, por ejemplo ["typeClient", "segmentationSimple"]. Solo se tendrán en cuenta los perfiles que hayan sufrido una modificación en alguna de estas segmentaciones. Solo se pueden escuchar segmentaciones a través de este método, no atributos de perfiles.

• UPDATED_SUBSCRIPTION : Obligatorio. Debe especificar la lista de suscripciones escuchadas, por ejemplo ["Newsletter", "Global"]. Solo se tendrán en cuenta los perfiles afectados por una suscripción/desuscripción para una de estas suscripciones. Solo se pueden escuchar suscripciones a través de este método, no atributos de perfiles.

nota

• Los campos afectados por el Webhook solo pueden ser atributos de perfil, suscripciones, segmentaciones o campos de tabla de datos. Los atributos técnicos no pueden ser considerados.
• Es necesario proporcionar el nombre exacto (sensible a mayúsculas y minúsculas) del atributo de perfil o campo de tabla, de lo contrario obtendrá un error.
• En el caso de las segmentaciones y las suscripciones, solo es necesario proporcionar su nombre.

"targetUrl"

El parámetro "targetUrl" corresponde a la URL de su elección en la que se enviarán los eventos.

"headers"

Este parámetro permite pasar encabezados de solicitud adicionales, especialmente para la autenticación necesaria para acceder a la URL objetivo.

"webhookPushType"

Este parámetro indica el modo utilizado para enviar los eventos. Puede ser:

• ONE_BY_ONE : cada llamada contendrá un solo evento.

• BULK : cada llamada compilará un conjunto de eventos, cuyo número será como máximo el valor especificado en el parámetro "maxBlockSize".

Consejo

Los webhooks masivos siguen siendo llamadas en tiempo real, especialmente útiles cuando se registran muchos eventos (creaciones, actualizaciones) al mismo tiempo. Pero los eventos no se encolan hasta que se alcance el "maxBlockSize". Cuando se registra un evento, se enviará individualmente si no se envía otro evento en unos segundos.

"maxBlockSize"

Si el Webhook está en modo BULK, especifica el número máximo de eventos que cada llamada puede contener (número entero entre 10 y 1000).

Este es el número máximo, no el número esperado antes de desencadenar una notificación: si el valor de "maxBlockSize" no se alcanza, la llamada se enviará después de 5 segundos.

Estructura de los elementos obtenidos

Los eventos transmitidos en la URL proporcionada siempre tendrán una estructura específica, que variará según el tipo de evento escuchado.

Para cada evento, se pueden proporcionar 3 tipos de información:

Información técnica

El evento siempre tendrá la siguiente información:

• "id": El primer parámetro "id" corresponde al identificador técnico de la suscripción.

• "tableId": Este es el identificador técnico de la tabla de perfiles o datos.

• "profileId": Este es el identificador técnico del perfil afectado o del perfil relacionado con la interacción de la tabla de datos.

• "eventType": Esto indica el tipo de evento escuchado.

• "tableType": Esto indica el tipo de tabla escuchada: tabla de perfiles o datos.

• "businessKey": Este es el atributo único definido técnicamente como la clave de negocio de la tabla de perfiles.

Información sobre los campos escuchados

La estructura del evento contendrá información para cada campo solicitado en el parámetro "onFields" al crear la suscripción Webhook. Esta información se encuentra en el conjunto "data". Se presenta como el nombre del atributo o campo de la tabla junto con el valor que toma para el evento desencadenante.

El parámetro "id" que aparece en el conjunto "data" corresponde al identificador técnico del evento.

Si un campo no tiene valor, aparecerá en la sección "fields".

Consejo

Solo se recuperarán los campos especificados en el parámetro "onFields" mediante el Webhook. Por lo tanto, es importante definir correctamente los campos que le interesan al crear la suscripción Webhook.

Información sobre el RGPD

Esta información solo aparecerá para eventos relacionados con una tabla de perfiles. Se completarán automáticamente y le proporcionarán información sobre el origen del evento y los datos relacionados.

Mantener esta información para poder justificar el origen de las interacciones de perfil (especialmente las suscripciones) es una buena práctica en términos de RGPD.

Se trata de:

• "dataCollectionSource": La fuente de recopilación de la información. Es el medio por el cual Actito ha recopilado la información.

• "dataCollectionWay": El método de recopilación de la información. Este dato indica la información técnica relacionada con el dispositivo utilizado por el perfil para generar esta interacción.

• "dataCollectionMoment": El momento de recopilación de la información. Es la fecha y hora en la que Actito registró la información.

Consejo

Para obtener más información sobre el contenido de las notificaciones webhooks, consulta el Portal de Desarrolladores.