¿Qué es un webhook?
Un Webhook es un procedimiento de comunicación entre aplicaciones que permite interacción en tiempo real a través del protocolo HTTP en circunstancias determinadas. Puedes enviar información (via POST) a una URL específica cuando sucede un evento predefinido en tu cuenta y generar una llamada a una URL predeterminada (webhooked).
Por ejemplo, cuando un código QR de tu cuenta es escaneado (QR_CODE_SCANNED), puedes programar que se envíe un SMS a un teléfono determinado y/o crear un registro en tu sistema de bases de datos.
¿Cómo creo un webhook?
Una vez que inicies sesión como administrador en tu cuenta White Label, selecciona a uno de tus usuarios y ve a la sección Webhooks. Allí puedes establecer una URL de destino para cada evento.
¿Qué eventos desencadenan un webhook?
Múltiples eventos en la plataforma pueden activar un webhook:
| Evento | Se activa... |
|---|
| QR_CODE_CREATED | cuando se genera un código QR |
| QR_CODE_SCANNED | cuando se escanea un código QR |
| VOUCHER_CREATED | cuando se crea un Cupón |
| VOUCHER_UPDATED | cuando se actualiza un Cupón |
| VOUCHER_REDEEMED | cuando se canjea un Cupón |
| VOUCHER_EXPIRED | cuando caduca un Cupón |
| LEAD_CREATED | cuando se envía un formulario |
| CALL_2_ACTION_BUTTON_CLICKED | cuando se hace click en un botón C2A |
| JOB_FINISHED | cuando finaliza una creación masiva de códigos QR de diseño personalizado |
¿Qué parámetros envía un webhook?
En función del evento, se genera una llamada a la URL configurada para el webhook que incluye ciertos parámetros a través de un POST request.
Parámetros estándar
En un webhook siempre se envían los siguientes parámetros:
| Parámetro | Descripción |
|---|
| event | El nombre del evento (Ej.: QR_CODE_ESCANNED) |
| timestamp | La hora en que ocurrió el evento |
| user | El usuario que creó el Código QR |
| code | La URL corta personalizada del código QR |
| secrettoken | La clave API secreta de la API de usuario. Puedes usar esta clave para verificar que una solicitud de webhook proviene de tu cuenta. |
Se escaneó un código QR
Si se escaneó un código QR, se envían estos parámetros adicionales:
| Parámetro | Descripción |
|---|
| redirects | Número de veces que se escaneó un código QR |
| visitors | El número de visitantes únicos que escanearon el código QR |
| device | El dispositivo desde el que se escaneó el código QR |
| os | El sistema operativo del dispositivo desde el que se escaneó el código QR |
| country | El país en el que se escaneó el código QR |
| lng/lat | Información de ubicación con un par lng/lat si un usuario acepta compartir sus datos de ubicación. |
Se actualizó un cupón
Si se actualizó un cupón, se envían estos parámetros adicionales:
| Parámetro | Descripción |
|---|
| title | Título del cupón |
| description | Descripción del cupón |
| Tipo de cupón |
| type | Tipo de cupón |
| UNIQUEIP Se puede canjear el cupón una vez por IP |
| UNIQUEID Se puede canjear el cupón una sola vez |
| productname | Opcionalmente se puede añadir un nombre de producto para el cupón |
| website | Opcionalmente se puede añadir un link en el cupón a una página web |
| couponnumber | Opcionalmente se puede asignar un número que aparecerá en el cupón |
| validfrom | Opcionalmente se puede añadir una fecha A PARTIR DE LA CUAL el cupón es válido |
| validto | Opcionalmente se puede añadir una fecha HASTA LA QUE el cupón es válido |
Se canjeó el cupón
Si se canjeó un cupón, se envían estos parámetros adicionales:
| Parámetro | Descripción | |
|---|
| status | Estado del canje | |
| SUCCESS | Se canjeó el cupón |
| VOUCHER_ALREADY_REDEEMED | El cupón ya se había canjeado anteriormente |
| VOUCHER_EXPIRED | El cupón había caducado |
| QUOTA_EXCEEDED | El límite de canjes se había excedido |
| type | Tipo de cupón | |
| UNIQUEIP | Se puede canjear el cupón una vez por IP |
| UNIQUEID | Se puede canjear el cupón una sola vez |
| eancode | | Si se canjea un cupón asociado a un código de barras EAN, el código EAN se transmitirá en el webhook. |
| uniqueid | | Si el código QR es un cupón canjeable una sola vez, se devuelve la identificación única del cupón. Esta es una de las identificaciones únicas cuando creas códigos QR masivos para un cupón canjeable de forma única. |
| Parámetro | Descripción |
|---|
| email | Dirección de e-mail del nuevo contacto |
| name | Nombre del nuevo contacto |
Se pulsó un botón C2A
Si se pulsó un botón C2A, se envían estos parámetros adicionales:
| Parámetro | Descripción |
|---|
| c2a | La URL de destino del botón Call-2-Action |
Finalizó un trabajo
Cuando finaliza una creación masiva descargable de códigos QR de diseño personalizado, se envían estos parámetros adicionales:
| Parámetro | Descripción |
|---|
| download | Un enlace para descargar el resultado del trabajo que es válido por 30 días |
Depuración
Si quieres generar la información enviada a tu servidor en un webhook, utiliza la siguiente secuencia de comandos PHP para mostrar todos los parámetros:
<?php
// Test WebHook and show parameters
error_log("Fired WebHook");
// Post Parameter
foreach ($_POST as $param_name => $param_val) {
error_log("$param_name: $param_val");
}
// Get Parameter
foreach ($_GET as $param_name => $param_val) {
error_log("$param_name: $param_val");
}
// if JSON submitted
$json = json_decode(file_get_contents('php://input'));Haz una prueba online de tu webhook
Con el servicio gratuito webhook.site, puedes testear un webhook al momento.
Copia la configuración de los webhook para otros usuarios
La API de administrador te permite copiar la configuración del webhook de un usuario y reutilizarla en otros perfiles de usuario.