Webhooks

4 minutos

24/01/2023

¿Qué es un webhook?
¿Cómo creo un webhook?
¿Qué eventos desencadenan un webhook?
¿Qué parámetros envía un webhook?
Depuración
Haz una prueba online de tu webhook
Copia la configuración de los webhook para otros usuarios

¿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.

Los webhooks solo están disponibles con nuestro plan White Label.

¿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.

Se envió un formulario

Por cada nuevo contacto, se envían estos parámetros adicionales:

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.