Webhooks de entrada

📥 Webhooks de Entrada

Recibe eventos de plataformas externas y otorga semillas a tus clientes automáticamente. Los webhooks de entrada te permiten conectar cualquier herramienta de terceros — aplicaciones de cuestionarios, formularios, plataformas de reseñas, Zapier, Make, y más — a tu programa de lealtad LoyaltyTree.

Cómo Funciona

El sistema de webhook de entrada utiliza un modelo de Fuentes & Códigos:

1. Crea una Fuente — Una fuente representa una plataforma o herramienta externa (por ejemplo, "Typeform", "Zapier", "Mi Aplicación de Cuestionarios"). Cada fuente obtiene una URL de webhook única y una clave secreta para seguridad.
2. Agrega Códigos a la Fuente — Cada código define una acción específica que otorga semillas (por ejemplo, "cuestionario_completado", "formulario_enviado", "cumpleaños_reclamado"). Tú estableces cuántas semillas otorga cada código, con límites opcionales.
3. Envía solicitudes POST — Tu plataforma externa envía una solicitud POST a la URL del webhook con el código y la información del cliente. LoyaltyTree encuentra o crea al cliente y otorga las semillas automáticamente.

Cómo Empezar

Paso 1: Crea una Fuente de Webhook

Navega a Tiendas → [Tu Tienda] → Integraciones → Webhooks de Entrada. Haz clic en + Agregar Fuente y dale un nombre que describa la plataforma externa (por ejemplo, "Cuestionarios de Typeform" o "Automatización de Zapier").

Cuando se crea la fuente, recibirás:

• URL del Webhook — El endpoint al que tu plataforma externa enviará solicitudes
• Secreto del Webhook — Una clave secreta para firmar solicitudes (recomendado por seguridad)

Paso 2: Agregar Códigos

Cada código representa una acción específica que deseas recompensar. Haz clic en + Agregar Código en tu fuente para crear uno.

Campo	Requerido	Descripción
Código	Sí	El valor exacto enviado en la carga útil del webhook (por ejemplo, cuestionario_completado). Esto debe coincidir con lo que envía tu plataforma externa.
Nombre para Mostrar	Sí	Un nombre amigable que se muestra en el panel de administración y el historial de transacciones (por ejemplo, "Cuestionario Completado").
Descripción	No	Una nota opcional para tu equipo sobre cuándo se utiliza este código.
Cantidad de Semillas	Sí	Cuántas semillas otorgar cada vez que se activa este código. Por defecto es 1.
Máx. Semillas/Cliente	No	El total máximo de semillas que un solo cliente puede ganar de este código. Deja vacío para ilimitado. Una vez que un cliente alcanza este límite, las llamadas de webhook posteriores para ellos devolverán éxito pero otorgarán 0 semillas.
Tiempo de Espera (horas)	No	Horas mínimas entre recompensas para el mismo cliente en este código. Previene abusos limitando la frecuencia con la que un cliente puede ganar semillas. Deja vacío para no tener tiempo de espera.
Habilitado	—	Alternar para habilitar o deshabilitar este código sin eliminarlo. Los códigos deshabilitados devuelven un error 403.

Códigos & Límites Explicados

Los códigos y sus límites trabajan juntos para darte un control preciso sobre cómo se otorgan las semillas:

Cantidad de Semillas

Cada código tiene una cantidad fija de semillas. Cada vez que se activa el webhook con ese código, el cliente recibe exactamente esa cantidad de semillas. Por ejemplo, si estableces "cuestionario_completado" a 5 semillas, cada llamada de webhook que califique otorgará 5 semillas.

Máx. Semillas por Cliente

Esto establece un límite de por vida por cliente por código. Es el total de semillas que ese cliente puede ganar de este código específico, no el número de veces que puede activarlo.

Tiempo de Espera (Horas)

Establece un tiempo de espera mínimo entre las recompensas de semillas para el mismo cliente en el mismo código. El temporizador de espera comienza desde la última recompensa exitosa.

Formato de Solicitud

Envía una solicitud POST a tu URL de webhook con el siguiente cuerpo JSON:

{
  "code": "tu_codigo_aqui",
  "customer": {
    "email": "cliente@ejemplo.com",
    "shopify_customer_id": "12345",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "metadata": {
    "quiz_score": 95,
    "source_page": "spring-quiz"
  }
}

* Al menos uno de email o shopify_customer_id es requerido. El correo electrónico es necesario cuando el cliente no existe ya en LoyaltyTree.

Verificación de Firma HMAC (Recomendado)

Para verificar que las solicitudes provienen genuinamente de tu plataforma (y no de alguien que encontró tu URL de webhook), firma tus solicitudes usando HMAC-SHA256.

Encabezados de firma soportados (LoyaltyTree verifica todos estos):

• X-Webhook-Signature
• X-Hub-Signature-256
• X-Signature

El valor de la firma puede ser ya sea el hash hexadecimal en bruto o prefijado con sha256= (ambos formatos son aceptados).

Alternativa: Autenticación de Token Simple

Si la firma HMAC no es posible en tu plataforma, puedes pasar tu secreto de webhook como un token simple en el encabezado X-Token. LoyaltyTree lo comparará directamente con tu secreto.

Ejemplo: Firmando con Node.js

const crypto = require('crypto');

const payload = JSON.stringify({
  code: 'cuestionario_completado',
  customer: { email: 'jane@example.com' }
});
const signature = crypto
  .createHmac('sha256', 'tu_secreto_de_webhook')
  .update(payload)
  .digest('hex');
fetch('https://loyaltytree.eco/webhooks/inbound/TU_ID_DE_FUENTE', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Webhook-Signature': signature
  },
  body: payload
});

Ejemplo: Firmando con Python

import hmac, hashlib, json, requests

payload = json.dumps({
    "code": "cuestionario_completado",
    "customer": {"email": "jane@example.com"}
})
signature = hmac.new(
    b'tu_secreto_de_webhook',
    payload.encode('utf-8'),
    hashlib.sha256
).hexdigest()
requests.post(
    'https://loyaltytree.eco/webhooks/inbound/TU_ID_DE_FUENTE',
    headers={
        'Content-Type': 'application/json',
        'X-Webhook-Signature': signature
    },
    data=payload
)

Ejemplo: Usando cURL (para pruebas)

curl -X POST https://loyaltytree.eco/webhooks/inbound/TU_ID_DE_FUENTE \
  -H "Content-Type: application/json" \
  -H "X-Token: tu_secreto_de_webhook" \
  -d '{"code":"cuestionario_completado","customer":{"email":"jane@example.com"}}'

Formato de Respuesta

Respuesta Exitosa (200)

{
  "success": true,
  "seeds_awarded": 5,
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef"
}

Exitoso pero Limitado (200)

Cuando un tiempo de espera o límite de semillas máximas impide la recompensa, aún obtienes una respuesta 200 pero con 0 semillas y una explicación:

{
  "success": true,
  "seeds_awarded": 0,
  "message": "Tiempo de espera activo. Intenta de nuevo en 18 hora(s)."
}

// o
{
  "success": true,
  "seeds_awarded": 0,
  "message": "Máximas semillas (15) ya otorgadas para este código."
}

Respuestas de Error

Ejemplos de Casos de Uso

Conectando con Zapier

Zapier es una de las formas más populares de conectar LoyaltyTree con cientos de otras aplicaciones. Estamos construyendo una integración dedicada de LoyaltyTree en la Tienda de Aplicaciones de Zapier, que hará que la configuración sea aún más fácil — búscala en el mercado de Zapier.

Mientras tanto, puedes usar la acción Webhooks de Zapier para conectarte ahora mismo:

Conectando con Make (Integromat)

También puedes usar el módulo HTTP / Hacer una solicitud de Make para enviar webhooks a LoyaltyTree. Configúralo de la misma manera que Zapier — establece la URL, agrega el cuerpo JSON con code y customer, y incluye tu secreto en el encabezado X-Token.

Registros de Webhook

Cada llamada de webhook de entrada se registra y es visible en la sección Webhooks de Entrada de tu página de Integraciones. Los registros muestran:

• Marca de Tiempo – Cuándo se recibió el webhook
• Fuente – Qué fuente lo recibió
• Estado – Éxito o fallo
• Detalles – Código utilizado, semillas otorgadas, o mensaje de error
• Carga Útil – El cuerpo completo de la solicitud (encriptado en reposo)

Utiliza los registros para verificar que tu integración esté funcionando correctamente y para solucionar cualquier problema.

Solución de Problemas

Seguridad

• Cada fuente obtiene un secreto de webhook único de 64 caracteres, autogenerado y encriptado en reposo
• Los secretos pueden ser regenerados en cualquier momento desde la configuración de la fuente (el antiguo secreto deja de funcionar inmediatamente)
• Las cargas útiles de las solicitudes están encriptadas en los registros por privacidad
• La verificación de firma utiliza comparación segura por tiempo para prevenir ataques de tiempo
• Las fuentes y los códigos pueden ser deshabilitados individualmente sin eliminarlos