¿Qué es un Webhook?

Un Webhook es un sistema utilizado por una aplicación para enviar información en tiempo real a otras aplicaciones. Un webhook envía la información al mismo tiempo en que ésta se registra, lo que significa que te permite obtener la información al momento. 

Hemos desarrollado los webhooks de Easypromos para enviar en tiempo real la información que se obtiene en un promoción a un sistema externo, para que así los organizadores de la promoción puedan programarse integraciones más avanzadas.

Ejemplo de casos de usos de webhooks en Easypromos:

• Recibir en tiempo real la información de un usuario nuevo que se registra en un concurso para añadirla en un CRM.
• Recibir en tiempo real la información del premio ganado por un usuario cuando gira una ruleta de premios para procesar el premio.
• Recibir en tiempo real la información de las monedas virtuales ganadas tras jugar un juego para sincronizarlas con el programa de puntos de un sistema de fidelización.

Nota: La integración con webhooks está disponible únicamente para las promociones creadas con la versión Marca Blanca y Corporate de la plataforma.

A continuación te explicamos cómo habilitar la integración con webhook en tu aplicación.

Tipos de eventos de los webhooks de Easypromos

Puedes utilizar los webhooks de Easypromos para configurar y recibir notificaciones cuando ocurre un evento específico.

Existen 4 tipos de eventos:

1. Webhook al registrar un nuevo usuario: se enviará la información de un usuario nuevo que se registra en la promoción. En caso que el usuario tenga que validar su email para registrarse, el webhook se enviará cuando el usuario valide su email. Este webhook es ideal para recibir la información de los usuarios registrados en tiempo real e insertarlos en un CRM o un sistema de gestión de usuarios.
2. Webhook al registrar una nueva nueva participación de usuario: se enviará la información concreta de la participación de un usuario. Por ejemplo, se envía la información del premio ganado por un usuario al girar una ruleta, o al jugar al rasca y gana, o se enviará los puntos obtenidos por un usuario en un juego.
3. Webhook al ganar un premio: se enviará cada vez que un usuario gane un premio e incluye la información completa del premio ganado y la del usuario ganador.
4. Webhook al completarse una transacción con monedas virtuales:  se envía cada vez que se realiza una transacción con monedas virtuales. La transacción puede ser con cantidad de monedas positiva, por ejemplo, cuando se ganan monedas al participar en una etapa, o con cantidad de monedas negativa, por ejemplo cuando se gastan monedas para cambiarla por premios. El webhook incluye la cantidad de la transacción, el saldo del usuario, y el usuario.

Antes de Empezar

Antes de iniciar el proceso deberás tener en cuenta los siguientes puntos:

• La integración con webhooks es una funcionalidad avanzada y, por lo tanto, se deben tener conocimientos avanzados en programación o bien contar con un desarrollador.
• Necesitas disponer de un servidor que acepte llamadas HTTP POST, así como poder escribir un script que realice una acción como respuesta.
• Los webhooks únicamente se pueden configurar en promociones del tipo Marca Blanca y Corporate.
• Puedes tener múltiples webhooks en una mismo promoción, por si quieres enviar la información en tiempo real a varios destinos.

Integrarse con los webhooks consta de 2 pasos:

• • Paso 1 - Preparar la promoción para que envíe el webhook: lo debe hacer la persona de Marketing que está configurando la promoción desde la interfaz de gestión de Easypromos. 
  • Paso 2 - Programar la recepción y el proceso del webhook: lo debe hacer la persona de Informática que programará el script o programa que recibirá el webhook, y procesará su información.

Paso 1. Preparar la promoción para que envíe el webhook

Para realizar este paso es necesario tener acceso al panel de gestión de la promoción en Easypromos. Este paso lo realizará normalmente la persona de marketing que gestiona la promoción y tiene acceso a Easypromos.

Para preparar la promoción para que se envíen los webhook deberá habilitarse la integración con webhooks desde el panel de gestión de la promoción en Easypromos. Deberás seguir estos pasos:

1. Accede a la página de gestión de la promoción y haz clic en ‘Integraciones’:

2. A continuación, haz clic en la imagen de ‘Webhooks’ para habilitar la integración:

3. Accederás a la página de configuración de la integración con webhooks, donde podrás configurar las opciones siguientes:

a) Tipo de evento: Es el tipo de evento que dispara el webhook. Tienes dos opciones:

• Al registrar un nuevo usuario: Se dispara el Webhook cuando se registra un nuevo usuarios en la promoción. El Webhook incluye toda la información de registro del usuario.
• Al registrar una nueva participación de un usuario: Se dispara el Webhook cuando se registra una nueva participación de un usuario en la promoción. El Webhook incluye la información de la participación, la del usuario participante, e incluye la información del premio, si la participación ganó un premio.
• Al ganar un premio: Se dispara el Webhook cada vez que se asigna un premio a un usuario (es decir el usuario gana el premio). El Webhook incluye la información del premio y la del usuario que ha ganado el premio. El Webhook no aplica para premios que se asignan por Sorteo Aleatorio. Aplica a los premios que se asignan por Momento Ganador, Directo al participar, por Probabilidad, o por Canjeo de monedas virtuales.
• Al realizar una transacción con una moneda virtual: Se dispara el Webhook cada vez que un usuario realiza una transacción con monedas virtuales. El Webhook incluye la información de la transacción y la del usuario. La transacción incluye la cantidad de la transacción (puede ser positiva o negativa según se haya ganado o gastado), y el saldo del usuario tras completarse la transacción.

b) Webhook URL: Es la URL donde enviremos la información. 

c) Webhook Key (opcional): Opcionalmente puedes añadir una referencia al Webhook a través de este campo de texto alfanumérico. Este campo se enviará junto con la información del Webhook. Utilízalo para validar que el Webhook realmente lo envía Easypromos.

Paso 2. Programar la recepción y proceso del webhook

Para realizar este paso es necesario tener conocimientos de programación web. Este paso lo realizará el programador que desarrollará la integración de la información obtenida en Easypromos con un sistema externo.

La información se enviará en peticiones HTTP_POST y el cuerpo del mensaje (payload) vendrá en formato JSON.

La especificación de la información del webhook ha sido definida siguiendo el estándar OpenApi 3.1. A continuación te presentamos el acceso a la especificación: 

• Al registrar un nuevo usuario: ver documentación y ejemplos.
• Al registrar una nueva participación de un usuario: ver documentación y ejemplos.
• Al ganar un premio: ver documentación y ejemplos.
• Al realizar una transacción con una moneda virtual: ver documentación y ejemplos.

Consideraciones en el desarrollo:

• El sistema considerará el intento de envío del webhook erróneo si la url en destino no responde en 5 segundos
• El sistema realizará 3 reintentos seguidos en caso de intento errónea. Tras 3 intentos erróneos, se descartará la tarea, y no se volverá a enviar. 

¿Puedo testear o validar los webhooks?

Sí, puedes utilizar servicios online gratuítos como por ejemplo requestbin.com para testear los webhooks:

1. Abre requestbin.com
2. Haz click en Crear nuevo Request. Deberás identificarte con una cuenta de Github o Google.
3. Copia la URL del Request creada en tu configuración de webhook

A continuación participa en la promoción y verifica el webhook recibido en requestbin.com:

¿Puedo editar o eliminar un webhook?

Si, una vez que hayas creado los diferentes webhooks, en la página de integraciones/webhooks, se visualizarán todos los webhooks que hay creados. Se podrán editar y o eliminar. Se verán en una lista, y con la tipología de cada uno de los webhooks (si es un webhook de usuarios únicos o de participaciones).