JeriCommerce registra todas las interacciones importantes de los clientes con tu programa de fidelización. Cuando conectas la integración Custom API, todos los eventos se envían como webhooks HTTP POST al endpoint configurado. Así puedes crear automatizaciones personalizadas, sincronizar datos o activar flujos de trabajo en cualquier sistema.

Configuración

Añade el endpoint webhook en Settings → Integrations → API, activa la función Events y guarda los cambios. Desde ese momento, cada evento de cliente que cumpla los requisitos se enviará como solicitud POST a tu URL.

Autenticación

Cada solicitud incluye el encabezado x-jericommerce-hmac-sha256, que contiene una firma cifrada con HMAC-SHA256 mediante el secreto que aparece en la página de integración. Valida esta firma en tu servidor para confirmar que la solicitud procede de JeriCommerce y evitar suplantaciones.

El tipo de evento se envía en el encabezado x-jericommerce-event-type. Úsalo para dirigir el payload al controlador adecuado.

Errores de entrega e intentos de nuevo

Los errores de red y las respuestas 408, 429 y 5xx se vuelven a intentar con una espera exponencial, hasta 10 intentos. Los errores permanentes del cliente, como 401, 403, 404 y 410, fallan de inmediato y no se vuelven a intentar. Haz que tu endpoint sea idempotente, ya que un fallo transitorio puede hacer que se entregue el mismo evento más de una vez.

JeriCommerce cuenta los errores permanentes consecutivos de cada integración API. Tras 10 errores permanentes, desactiva la función Events de esa integración para dejar de enviar solicitudes a un endpoint que no funciona. Corrige el endpoint y vuelve a activar Events en los ajustes de integración de API. Una entrega correcta restablece el contador de errores consecutivos.

Payload base

Todos los webhooks comparten esta estructura base:

{
  "email": "customer@example.com",
  "id": "event-uuid",
  "customerId": "customer-uuid",
  "campaignId": "campaign-uuid",
  "url": "https://...",
  "browser": "Chrome 120",
  "createdAt": "2026-03-08T12:00:00Z",
  "properties": { ... }
}

Los campos indicados como opcionales pueden no aparecer en todos los eventos:

  • campaignId: solo cuando el evento está vinculado a una campaña concreta
  • url y browser: solo en eventos originados en la web

Todos los eventos

A continuación se muestra la lista completa de los 19 eventos que se envían al webhook. La columna Event name coincide con el valor del encabezado x-jericommerce-event-type. La columna Key properties muestra los campos disponibles en el objeto properties de cada evento.

Event name Cuándo se activa Key properties
Customer
Customer created Se registra un cliente nuevo (no durante la sincronización inicial) email, origin, referral, utmCampaign, utmMedium, utmSource, firstName, lastName, phoneNumber
Customer birthday Una tarea diaria programada comprueba las fechas de nacimiento (se ejecuta alrededor de las 9:00 UTC) age (calculada a partir de la fecha de nacimiento)
Customer scanned El cliente escanea un código NFC en una ubicación física mediante Shopify POS Contexto de ubicación y dispositivo
Customer tapped El cliente toca un dispositivo VTAP/NFC Contexto del dispositivo
Wallet pass
Wallet pass requested El cliente solicita un enlace para descargar un Wallet Pass email, referral, downloadLink, utmCampaign, utmSource, utmMedium
Wallet pass installed El cliente añade el pase a Apple Wallet o Google Wallet referral, utmCampaign, utmSource, utmMedium
Wallet pass uninstalled El cliente elimina el pase de su cartera referral, utmCampaign, utmSource, utmMedium
Loyalty
Balance changed Se añaden o eliminan puntos de fidelización (compras, reembolsos o ajustes manuales) amount, reference, previous (saldo antes del cambio), pointsToNextReward, nextRewardName
Tier changed Cambia el nivel de fidelización del cliente (se recalcula a diario a las 5:00 o cuando cambia el saldo) previous (nombre del nivel), current (nombre del nivel)
Coupons
Coupon assigned Se asigna un código de cupón a un cliente code, header, body, slug, assignedFrom, installUrl
Coupon expiring Un código de cupón asignado y sin usar caduca al día siguiente según la zona horaria de la tienda couponId, couponCodeId, couponSlug, code, expiresAt
Coupon pass installed El cliente añade un pase de cupón a Apple Wallet o Google Wallet referral, utmCampaign, utmSource, utmMedium
Coupon pass uninstalled El cliente elimina un pase de cupón de su cartera referral, utmCampaign, utmSource, utmMedium
Gift cards
Gift card sent El administrador envía una tarjeta regalo a un cliente code, header, body, slug, assignedFrom, installUrl, mailSent
Rewards
Reward redeemable Una recompensa pasa a estar disponible para que el cliente la canjee rewardId, rewardLink, rewardTitle, rewardValue, rewardCost, customerRemainingBalance
Reward redeemed El cliente canjea una recompensa rewardId, rewardLink, rewardTitle, code
Reward refunded El administrador reembolsa una recompensa canjeada anteriormente claimId
Engagement
Wallet click El cliente hace clic en un enlace de su Wallet Pass url, browser, utmCampaign, utmSource ("wallet"), utmMedium ("wallet_pass")
Wallet visit El cliente visita o abre la aplicación web de su Wallet Pass name, url, browser, referral, utmCampaign, utmSource, utmMedium

Ya está todo listo. Tu endpoint recibirá datos en tiempo real de cada interacción de clientes en JeriCommerce.

Coupon expiring

El evento Coupon expiring está disponible mediante el mapeo genérico de eventos de la API. Se emite para un código de cupón asignado a un cliente, que aún no se ha usado y que caduca al día siguiente según la zona horaria de Shopify de la tienda. Si JeriCommerce no puede leer esa zona horaria, utiliza UTC. No es un aviso que se envíe exactamente 24 horas antes.

Las propiedades del evento incluyen couponId, couponCodeId, couponSlug, code y expiresAt. Puedes usarlas para crear tu propia automatización. El evento no envía automáticamente un correo electrónico ni una notificación push y no está disponible como activador de Shopify Flow.