Webhooks: cómo automatizar los eventos de Perkstar con notificaciones de API en tiempo real
Aprenda a configurar webhooks para la automatización de eventos en tiempo real. Guía completa para crear puntos finales de webhook, suscribirse a tipos de eventos, recibir cargas útiles JSON, implementar verificación de seguridad, probar entregas y solucionar problemas de webhook. Descripción general de
Los webhooks
permiten la automatización basada en eventos en tiempo real al enviar notificaciones instantáneas desde Perkstar a sus propios sistemas o aplicaciones de terceros cada vez que ocurren eventos específicos. A diferencia de las integraciones tradicionales que buscan cambios según un cronograma, los webhooks le envían datos inmediatamente cuando sucede algo, lo que permite reacciones instantáneas y una automatización perfecta.
Qué puedes hacer con los webhooks:
Reciba notificaciones en tiempo real cuando los clientes realicen acciones (registrarse, agregar tarjeta, realizar compras)
Activa flujos de trabajo automatizados en tus propios sistemas basados en eventos de fidelización
Sincronice datos de fidelidad al instante con aplicaciones o bases de datos personalizadas
Cree integraciones avanzadas con plataformas que no son compatibles de forma nativa
Cree una lógica empresarial personalizada que responda a la actividad del programa de fidelización
Monitoree todos los eventos de lealtad en tiempo real para análisis o alertas Consejo
: Los webhooks eliminan retrasos y trabajo manual al enviar información a sus sistemas en el momento en que ocurren los eventos. En lugar de buscar actualizaciones cada hora o cada día, sus aplicaciones reciben notificaciones instantáneas, lo que permite la participación inmediata del cliente, informes en tiempo real y sistemas sincronizados en toda su pila de tecnología empresarial.
Quién debería usar webhooks: Desarrolladores de
: Creación de integraciones y automatización personalizadas
Equipos técnicos: Implementación de automatización avanzada del flujo de trabajo Administradores de
IT: Conexión de Perkstar a sistemas propietarios
Usuarios avanzados: Creación de lógica empresarial personalizada más allá de las integraciones estándar
Conocimientos técnicos necesarios:
Comprensión de HTTP/HTTPS y REST API
Capacidad para recibir y analizar datos JSON
Habilidades básicas de programación (cualquier lenguaje que maneje solicitudes HTTP)
Acceso a un servidor web o función de nube para recibir llamadas de webhook
Antes de comenzar Requisitos de
:
Cuenta activa Perkstar
Permisos de propietario o administrador de la cuenta
Soporte de Webhook incluido en su plan de suscripción (consulte la sección Plan)
Conocimiento técnico de APIs y desarrollo web.
Lo que necesitarás:
Infraestructura técnica:
Un punto final HTTPS de acceso público (URL) para recibir datos de webhook
Servidor web, función de nube o servicio de webhook (Zapier, Make, n8n)
Capacidad para analizar cargas útiles JSON
(Recomendado) Verificación de firma de Webhook para seguridad
Configuración de desarrollo:
El entorno de prueba está separado de la producción.
Sistema de registro para rastrear webhooks entrantes
Manejo de errores y lógica de reintento
Monitoreo de alertas para fallas de webhooks
Comprensión de los webhooks frente a las integraciones
Webhooks:
Notificaciones push en tiempo real
Escribe código personalizado para manejar eventos.
Máxima flexibilidad y personalización
Requiere implementación técnica
Perfecto para: Sistemas personalizados, flujos de trabajo únicos, requisitos en tiempo real
Integraciones prediseñadas:
Conexiones preconfiguradas a plataformas populares
No se requiere codificación
Limitado a integraciones disponibles
Configuración más sencilla, pero menos flexible
Perfecto para: Casos de uso estándar, usuarios no técnicos, plataformas comunes
Utilice webhooks cuando:
Necesitas notificaciones de eventos en tiempo real
Te estás integrando con sistemas personalizados o propietarios
Las integraciones prediseñadas no satisfacen sus necesidades
Quiere un control total sobre el procesamiento de datos
Estás creando flujos de trabajo de automatización avanzados
Accediendo a la sección Webhooks
Cómo navegar a webhooks
Desde tu panel de control:
Inicie sesión en su cuenta Perkstar
Haga clic en Configuración (icono ⚙️) en el menú de la izquierda
Haga clic en la pestaña Webhooks en la parte superior de la pantalla Configuración
Nota: La pantalla Webhooks muestra todas las herramientas y opciones de administración de webhooks.
Diseño de pantalla de webhooks
La sección Webhooks contiene dos áreas principales:
Lista de webhooks (tabla):
Muestra todos los webhooks existentes
Muestra URL, estado y recuento de eventos para cada webhook
Descripción rápida de todas las configuraciones de webhooks activos
Botón Agregar webhook:
Crea nuevas configuraciones de webhook
Abre la ventana emergente de creación de webhook.
Comprender la lista de webhooks
Columnas de la tabla de webhooks
Todos los webhooks configurados aparecen en una tabla con la siguiente información:
URL:
El punto final que recibe notificaciones de webhooks
Dirección HTTPS completa de su servidor o servicio receptor
Ejemplo: https://api.yourcompany.com/webhooks/perkstar
Estado:
Estado operativo actual del webhook
Activado: Webhook está activo y envía notificaciones.
Desactivado: Webhook está en pausa y no envía notificaciones
Le permite desactivar temporalmente los webhooks sin eliminarlos
Recuento de eventos:
Número de tipos de eventos a los que está suscrito este webhook
Número más alto = el webhook recibe más tipos de notificaciones
Haga clic en el webhook para ver qué eventos específicos están habilitados
Ver detalles del webhook
Para ver o editar un webhook existente:
Ubique el webhook en la lista de webhooks
Haga clic en la fila del webhook
Se abre la ventana emergente de detalles del webhook que muestra la configuración completa
Detalles mostrados:
URL completo
Todos los tipos de eventos suscritos con casillas de verificación
Estado actual (alternancia habilitado/deshabilitado)
Fecha de creación
Última información de entrega (si está disponible)
Opciones de edición y eliminación
Crear un nuevo webhook
Paso 1: prepare su terminal
Advertencia: Antes de crear un webhook en Perkstar, asegúrese de que su punto final de recepción esté listo.
Su punto final debe:
Ser de acceso público a través de HTTPS (no HTTP)
Aceptar solicitudes HTTP POST
Devuelva el código de estado 200 para una recepción exitosa
Responda dentro de 5 a 10 segundos (procesamiento rápido)
Analizar el cuerpo de la solicitud JSON
Manejar los reintentos de webhook con elegancia
Recomendaciones de seguridad:
Utilice HTTPS (requerido por seguridad)
Validar firmas de webhooks (si las proporciona Perkstar)
Implementar limitación de tasas para evitar abusos
Registre todos los webhooks entrantes para depurarlos
Utilice reglas de firewall para restringir el acceso si es posible
Ejemplo de configuración de punto final (Node.js/Express):
Paso 2: crea el webhook en Perkstar
Para agregar un nuevo webhook:
Vaya a Configuración → pestaña Webhooks
Haga clic en el botón Agregar webhook
Se abre la ventana emergente Agregar webhook
Paso 3: Configurar los ajustes del webhook
Ingrese al webhook URL:
En el campo URL en la parte superior de la ventana emergente, ingrese la dirección de su punto final
Debe ser un HTTPS completo URL
Ejemplo: https://api.yourcompany.com/webhooks/perkstar
Vuelva a verificar si hay errores tipográficos: los URL incorrectos fallarán
Seleccionar tipos de eventos:
Debajo del campo URL, verá una lista de tipos de eventos disponibles
Cada tipo de evento tiene una casilla de verificación
Marque la casilla de verificación para cada evento que desee recibir
Suscríbete solo a los eventos que realmente necesitas (reduce el tráfico innecesario)
Paso 4: Habilite el Webhook
Establecer estado del webhook:
Localice el botón de alternancia Estado en la ventana emergente
Alternar a habilitado (posición ON)
Si desea guardar el webhook pero aún no activarlo, déjelo Desactivado
Webhooks habilitados:
Comenzar a enviar notificaciones inmediatamente
Se activará para cualquier evento suscrito que ocurra
Se puede desactivar más tarde sin eliminar
Webhooks deshabilitados:
La configuración se guarda pero no se envían notificaciones
Útil para pruebas o pausas temporales
Se puede habilitar en cualquier momento
Paso 5: Guarde el webhook
Para completar la creación del webhook:
Revisar todas las configuraciones (URL, eventos, estado)
Haga clic en el botón Agregar Webhook en la parte inferior de la ventana emergente.
Webhook se crea y se agrega a la lista de Webhooks
Información: Si está habilitado, el webhook comienza a enviar notificaciones inmediatamente.
Después de la creación:
Aparece un nuevo webhook en la tabla de lista de webhooks La columna
Event Count muestra el número de eventos suscritos La columna de estado
muestra Activado o Desactivado
Pruebe el webhook activando un evento de suscripción
Tipos de eventos disponibles
Comprensión de los tipos de eventos
Información: Los tipos de eventos representan acciones o cambios específicos que ocurren en su cuenta Perkstar. Cuando te suscribes a un tipo de evento, tu webhook recibe una notificación cada vez que ocurre ese evento.
Tipos de eventos comunes
Eventos para clientes:
cliente.creado: se registra o se agrega un nuevo cliente
cliente.updated - Cambios en la información del perfil del cliente
cliente.deleted: el cliente se elimina del sistema Eventos de tarjeta de fidelización
: Tarjeta
instalada: el cliente agrega la tarjeta a la billetera digital
card.updated - Información de la tarjeta o cambios de diseño
card.deleted: el cliente retira la tarjeta de la billetera
Eventos de transacción: Transacción
creada: puntos, sellos o reembolsos agregados
transacción.completada - Transacción finalizada y confirmada
transacción.reversa: transacción cancelada o puntos deducidos
Eventos de recompensa:
recompensa.emitido: el cliente obtiene una recompensa
recompensa.canjeada: el cliente utiliza/reclama una recompensa
recompensa.expirada: la recompensa no reclamada caduca
Eventos de notificación push:
push.sent: notificación push entregada al cliente
push.opened: el cliente abre la notificación push
push.failed - Error en la entrega de notificaciones push
Eventos de comentarios:
comentarios.recibidos: el cliente envía comentarios o calificaciones
comentarios.updated - Se modifica el comentarios
Eventos de referencia:
referido.creado - Nueva referencia iniciada
referido.completado: la referencia se convierte correctamente
Nota: Los tipos de eventos disponibles pueden variar según el plan y la versión de Perkstar. Consulte la ventana emergente Agregar webhook para obtener la lista completa de eventos disponibles para su cuenta.
Elegir a qué eventos suscribirse
Mejores prácticas para la selección de eventos:
Empezar mínimo:
Suscríbete solo a los eventos que necesites activamente
Menos eventos = lógica más simple y menos datos para procesar
Siempre puedes agregar más eventos más tarde
Combinaciones iniciales comunes:
Seguimiento de la actividad del cliente: cliente.creado, transacción.completada
Sincronización CRM en tiempo real: cliente.creado, cliente.actualizado, transacción.creada
Automatización de recompensas: recompensa.emitida, recompensa.canjeada
Seguimiento del compromiso: tarjeta.instalada, push.abierta, respuesta.recibida
Considere el volumen de eventos:
transaction.created puede activarse muchas veces al día (alto volumen)
desencadenantes creados por el cliente con menos frecuencia (menor volumen)
Asegúrese de que su sistema pueda manejar el volumen de webhook esperado
Eventos relacionados con el grupo:
Consejo: Si necesita un evento del ciclo de vida, a menudo necesitará el conjunto completo. Ejemplo: cliente.creado, cliente.actualizado, cliente.eliminado juntos. Esto garantiza que su sistema permanezca sincronizado con todos los cambios.
Estructura de carga útil del webhook
Qué datos se envían
Información: Cuando ocurre un evento, Perkstar envía una solicitud HTTP POST a su webhook URL que contiene datos JSON sobre el evento.
Estructura de carga útil estándar:
Campos de carga útil comunes
tipo_evento (cadena):
Identifica qué evento ocurrió
Ejemplo: "cliente.creado", "transacción.completada"
Utilice esto para enrutar webhooks a los controladores adecuados
event_id (cadena):
Identificador único para este evento específico
Uso para idempotencia (detección de entregas duplicadas)
Incluir en registros para solucionar problemas
marca de tiempo (ISO 8601 fecha y hora):
Cuando ocurrió el evento
Ejemplo: "2025-10-14T15:30:00Z"
Zona horaria UTC
ID_cuenta (cadena):
Su identificador de cuenta Perkstar
Útil si un punto final maneja varias cuentas
Se puede utilizar para enrutar a la base de datos/inquilino correcto
datos (objeto):
Detalles específicos del evento
La estructura varía según el tipo de evento.
Contiene la carga útil real (información del cliente, detalles de la transacción, etc.)
Cargas útiles de ejemplo por tipo de evento
cliente.creado:
transacción.completada:
recompensa.emitida:
Manejo de cargas útiles de webhook
Mejores prácticas para el procesamiento de carga útil:
Validar estructura de carga útil:
Compruebe que existan los campos obligatorios
Verificar que los tipos de datos sean correctos
Maneje con elegancia los campos faltantes o inesperados
Utilice event_id para idempotencia:
Almacene event_ids procesados para detectar duplicados
Si recibe el mismo event_id dos veces, omita el procesamiento
Previene acciones duplicadas (cobro doble, registros duplicados)
Analice los datos con cuidado:
Utilice el analizador JSON apropiado para su idioma
Manejar errores de análisis (JSON con formato incorrecto)
Validar datos antes de usarlos en lógica empresarial.
Responda rápidamente:
Advertencia: Devuelve el estado 200 inmediatamente después de recibirlo. Procesar webhook de forma asincrónica (cola para procesamiento). No realice operaciones largas antes de responder. Perkstar volverá a intentarlo si no responde rápidamente.
Ejemplo de verificación de idempotencia (pseudocódigo):
Probando sus webhooks
Por qué las pruebas son fundamentales
Antes de confiar en webhooks en producción:
Verifique que su punto final reciba webhooks correctamente
Asegúrese de que el análisis de la carga útil funcione como se esperaba
Confirme que su lógica empresarial maneje los eventos correctamente
Identificar y solucionar cualquier problema antes de que afecte a los clientes.
Estrategias de prueba
1. Utilice herramientas de prueba de webhooks:
Webhook.site: servicio gratuito que muestra webhooks entrantes
RequestBin: punto final temporal para inspeccionar cargas útiles de webhooks
Cartero: envíe solicitudes de prueba a su punto final manualmente
2. Cree eventos de prueba en Perkstar:
Registrar un cliente de prueba
Realizar una transacción de prueba
Activar eventos a los que te has suscrito
Verifique que los webhooks lleguen a su punto final
3. Verifique sus registros:
Revisar los registros del servidor para solicitudes POST entrantes
Verificar la estructura de carga útil JSON
Compruebe si hay errores de análisis
Confirmar que la lógica empresarial se ejecuta correctamente
4. Escenarios de error de prueba:
¿Qué sucede si su punto final no funciona?
¿Cómo maneja su sistema las cargas útiles con formato incorrecto?
¿Funciona la idempotencia (enviar event_id duplicado)?
¿Puede su sistema recuperarse de fallas temporales?
Uso de Webhook.site para realizar pruebas
Prueba rápida antes de la producción:
Ir a https://webhook.site
Copie el URL único proporcionado
En Perkstar, cree un webhook de prueba con ese URL.
Suscríbete a un evento como cliente.created
Crear un cliente de prueba en Perkstar
Consulte webhook.site; verá la carga útil del webhook.
Revisar la estructura y los campos de datos de JSON
Beneficios:
No se requiere codificación
Ver webhooks en tiempo real
Inspeccionar encabezados y carga útil
Perfecto para comprender la estructura de carga útil antes de construir
Gestión de webhooks existentes
Editar un webhook
Para modificar un webhook existente:
Vaya a Configuración → pestaña Webhooks
Haga clic en el webhook que desea editar en la lista.
Se abre la ventana emergente de detalles del webhook.
Haz tus cambios:
Actualice el URL si se cambia el punto final
Marcar o desmarcar tipos de eventos
Alternar estado (Activar/Desactivar)
Haga clic en el botón Guardar o Actualizar
Información: Los cambios entran en vigor inmediatamente.
Cuándo editar webhooks:
Cambios en el terminal URL (nuevo servidor, servicio diferente)
Necesitas tipos de eventos adicionales
Quieres reducir los eventos a un volumen más bajo
Desactivación temporal por mantenimiento
Habilitar y deshabilitar webhooks
Para deshabilitar temporalmente un webhook:
Haga clic en el webhook de la lista.
Cambie el interruptor de Estado a Desactivado
Haga clic en Guardar
Nota: La configuración del webhook se conserva pero no se envían notificaciones.
Para volver a habilitar un webhook:
Haga clic en el webhook
Cambiar estado a habilitado
Haga clic en Guardar
Consejo: Webhook reanuda inmediatamente el envío de notificaciones.
Casos de uso para deshabilitar:
Mantenimiento de endpoints o actualizaciones de servidores
Solución de problemas de webhooks
Pausa temporal durante la prueba
Cierre estacional de negocios
Beneficios frente a eliminación:
La configuración se conserva (URL, eventos)
Fácil de volver a habilitar más tarde
No es necesario reconfigurar desde cero
Puede desactivar/activar varias veces
Eliminar un webhook
Para eliminar permanentemente un webhook:
Haga clic en el webhook de la lista.
Localice el botón Eliminar en la ventana emergente de detalles.
Confirmar la eliminación cuando se le solicite
El webhook se elimina de la lista
Después de la eliminación:
Webhook deja de enviar notificaciones inmediatamente
La configuración no se puede recuperar (se debe recrear)
Endpoint ya no recibirá ninguna solicitud de Perkstar
No afecta a ningún otro webhook
Cuándo eliminar webhooks:
El punto final está fuera de servicio permanentemente
Proyecto de integración cancelado
El webhook se creó solo para realizar pruebas.
Consolidar varios webhooks en uno
Antes de eliminar:
Exportar la configuración del webhook para documentación
Notificar a los miembros del equipo que pueden confiar en el webhook
Asegúrese de que ningún flujo de trabajo crítico dependa del webhook
Considere deshabilitarlo primero para probar el impacto antes de la eliminación permanente
Mejores prácticas de seguridad
Requisitos de HTTPS
Advertencia: Utilice siempre HTTPS, nunca HTTP. Los webhooks HTTP envían datos sin cifrar a través de Internet. Cualquiera puede interceptar y leer datos confidenciales de los clientes. Perkstar puede requerir HTTPS para todos los webhooks.
Configurando HTTPS:
Utilice proveedores de nube con HTTPS integrado (AWS, Azure, Google Cloud)
Obtenga el certificado SSL gratuito de Let's Encrypt
Utilice servicios de webhook que proporcionen puntos finales HTTPS
Nunca implementes webhooks de producción a través de HTTP
Verificación de firma de webhook
Información: Perkstar puede incluir una firma criptográfica en los encabezados del webhook, lo que le permite verificar que el webhook realmente proviene de Perkstar y no fue falsificado.
Por qué es importante:
Evita que los atacantes envíen webhooks falsos a su punto final
Garantiza la integridad de los datos (el webhook no se modificó durante el tránsito)
Requerido para procesar acciones sensibles (pagos, cambios de cuenta)
Cómo verificar (pseudocódigo):
Consulte la documentación de Perkstar:
Nombre del encabezado de firma
Algoritmo hash utilizado (HMAC-SHA256 típico)
Dónde encontrar/configurar el secreto del webhook
Código de verificación de ejemplo para su idioma
Control de acceso
Restringir el acceso al punto final:
Utilice reglas de firewall para limitar las IP que pueden acceder a su punto final de webhook
Implementar limitación de velocidad (evitar abuso si se descubre URL)
Requerir encabezados de autenticación además de la verificación de firma
Registre todas las solicitudes de webhooks para auditoría de seguridad
No exponga datos confidenciales:
No incluya claves o contraseñas API en el webhook URL.
Utilice el cuerpo POST para los datos, no los parámetros de consulta URL
Asegúrese de que los mensajes de error no filtren información del sistema
Desinfectar registros para eliminar datos confidenciales de los clientes
Manejo y registro de errores
Registro completo:
Registre todos los webhooks entrantes con marca de tiempo y event_id
Registre la carga útil para la depuración (tenga en cuenta la privacidad de los datos)
Resultados del procesamiento de registros (éxito, fracaso, errores)
Configurar alertas para fallas repetidas del webhook
Manejo elegante de errores:
Detecte y registre todos los errores durante el procesamiento del webhook
Devuelve 200 incluso si falla la lógica empresarial (acuse de recibo)
Utilice la cola de mensajes no entregados para el procesamiento fallido de webhooks
Reintentar operaciones fallidas con retroceso exponencial
Ejemplo de manejo de errores:
Patrones de webhook avanzados
Múltiples webhooks para diferentes propósitos
Puede crear múltiples webhooks con diferentes configuraciones.
Ejemplo de arquitectura:
Webhook 1: Eventos de clientes → Se sincroniza con CRM (cliente.creado, cliente.actualizado)
Webhook 2: Eventos de transacción → Actualiza el sistema de contabilidad (transacción.completada)
Webhook 3: Todos los eventos → Envíos a la plataforma de análisis (todos los tipos de eventos)
Webhook 4: Eventos de recompensa → Activa el flujo de trabajo de cumplimiento (recompensa.emitida, recompensa.canjeada) Beneficios de
:
Separación de preocupaciones (diferentes sistemas manejan diferentes eventos)
Fallo independiente (el fallo de un webhook no afecta a los demás)
Depuración y monitoreo más sencillos
Seguridad/autenticación diferente por webhook Patrón de distribución en abanico
Consejo
: Enviar webhooks a la cola de mensajes para su distribución. Su punto final de webhook recibe webhooks Perkstar y los publica en la cola de mensajes (RabbitMQ, AWS SQS, etc.). Varios consumidores procesan eventos de forma independiente. Beneficios de
:
Escalabilidad (varios trabajadores procesan webhooks)
Fiabilidad (la cola almacena eventos si los consumidores no funcionan)
Flexibilidad (agregar nuevos consumidores sin cambiar el webhook)
Desacoplamiento (recibo de webhook separado del procesamiento)
Lógica de reintento de webhook
Comprensión de la entrega de webhooks:
Perkstar puede reintentar automáticamente los webhooks fallidos
Se producen reintentos si su terminal no devuelve el estado 200
Tiempo de reintento: normalmente inmediato, 1 minuto, 5 minutos, 30 minutos
Después del número máximo de reintentos, el webhook puede marcarse como fallido
Su terminal debe:
Devuelve 200 rápidamente (menos de 5 segundos)
Manejar entregas duplicadas con elegancia (idempotencia)
No depende del procesamiento sincrónico
Webhooks en cola para procesamiento asincrónico
Casos de uso comunes
Sincronización CRM en tiempo real
Objetivo: Mantenga CRM actualizado instantáneamente con la actividad del programa de fidelización Configuración de
:
Suscríbase a: cliente.creado, cliente.actualizado, transacción.completada
Webhook envía datos a CRM API
Los registros de los clientes permanecen sincronizados en tiempo real Beneficios de
:
El equipo de ventas ve la actividad de fidelización inmediatamente
Sin exportación/importación manual de datos
Vista completa del cliente en todos los sistemas
Cumplimiento de recompensas personalizadas
Objetivo: Cumplir recompensas automáticamente fuera de Perkstar Configuración de
:
Suscríbase a: recompensa.emitida, recompensa.redeemed
Webhook activa el sistema de cumplimiento (enviar correo electrónico con código, crear orden de envío, etc.)
Confirmación enviada de vuelta a Perkstar Beneficios de
:
Entrega de recompensa instantánea
Integración con sistemas externos (tarjetas de regalo electrónicas, envío API)
El flujo de trabajo automatizado reduce el trabajo manual
Paneles de inteligencia empresarial
Objetivo: Panel de análisis en tiempo real con métricas de lealtad Configuración de
:
Suscríbete a: Todos los tipos de eventos
Webhook envía datos a la base de datos de análisis
Base de datos de consultas del panel para métricas en vivo Beneficios de
:
Visibilidad en tiempo real del rendimiento del programa de fidelización
Informes personalizados más allá del análisis integrado de Perkstar
Combine datos de fidelización con otras métricas comerciales
Automatización de la participación del cliente
Objetivo: Activar promoción personalizado basado en el comportamiento de lealtad
Configuración:
Suscríbase a: transacción.completada, recompensa.emitida, comentarios.recibidos
Webhook activa una plataforma de automatización de promoción
Mensajes de seguimiento personalizados enviados automáticamente
Beneficios:
Respuesta inmediata a las acciones del cliente.
El compromiso personalizado mejora la lealtad
El flujo de trabajo automatizado ahorra tiempo al equipo de promoción
Solución de problemas de webhooks
Webhook no recibe eventos
Problema: ha creado un webhook pero no llegan notificaciones
Pasos para la solución de problemas:
Verifique que el webhook esté habilitado:
Verifique la columna Estado en la lista de webhooks
Abra los detalles del webhook para confirmar que el estado de alternancia es ON.
Habilitar si está deshabilitado
Verifique que URL sea correcto:
Abra los detalles del webhook y verifique URL
Asegúrese de que no haya errores tipográficos ni espacios adicionales
Confirme que es el punto final correcto (no localhost o URL interno)
Pruebe la accesibilidad del punto final:
Utilice curl o Postman para enviar una solicitud POST de prueba a su URL
Asegúrese de que el punto final sea de acceso público
Verifique que el firewall no esté bloqueando las solicitudes de las IP Perkstar
Activar un evento de prueba:
Realizar manualmente una acción que debería desencadenar un evento de suscripción
Ejemplo: si está suscrito a cliente.creado, cree un cliente de prueba
Compruebe si el webhook llega a su punto final
Revisar las suscripciones a eventos:
Abrir detalles del webhook
Verifica que hayas marcado las casillas de los eventos que deseas
El recuento de eventos debe coincidir con el número esperado
Errores de devolución de terminales
Problema: Los webhooks llegan pero su punto final devuelve códigos de estado 4xx o 5xx
Causas comunes y soluciones:
Análisis JSON no válido:
Asegúrese de que su código analice JSON correctamente
Maneje con gracia el JSON con formato incorrecto
Registre la carga útil sin procesar para depurar
Problemas de autenticación/autorización:
Si su punto final requiere autenticación, asegúrese de que el webhook pueda omitirse o tenga credenciales
Verificar que la lógica de verificación de firmas sea correcta
Verifique si hay tokens o certificados vencidos
Errores de tiempo de espera:
Su terminal debe responder en un plazo de 5 a 10 segundos
Procesar webhooks de forma asincrónica (devolver 200 inmediatamente y luego procesar)
Utilice la cola de mensajes para operaciones de larga duración
Errores internos del servidor:
Consulte los registros de su aplicación para obtener detalles sobre los errores.
Corregir errores en el código de manejo de webhooks
Agregue manejo y registro de errores completos
Entregas de webhooks duplicados
Problema: el mismo evento entregado varias veces
Causas:
Su punto final no devolvió 200 lo suficientemente rápido (se reintentó Perkstar)
Problemas de red provocaron un reintento
Este es un comportamiento normal: los webhooks deben ser idempotentes.
Solución: implemente la idempotencia usando event_id:
Para almacenamiento persistente:
Almacenar event_ids en la base de datos
Verifique la base de datos antes de procesar
Configure TTL en event_ids almacenados (elimine después de 30 días)
A las cargas útiles del webhook les faltan datos esperados
Problema: llega el webhook pero no contiene los campos que necesita
Solución de problemas:
Verifique la estructura de carga útil:
Registre la carga útil completa para ver qué se envía realmente
Comparar con la estructura esperada
Asegúrate de estar buscando en el objeto anidado correcto
Verificar tipo de evento:
Diferentes eventos tienen diferentes estructuras de carga útil.
Asegúrese de suscribirse al evento correcto para obtener los datos que necesita
Consulte la documentación de Perkstar para conocer los esquemas de carga útil.
Manejar campos nulos/faltantes:
Es posible que no todos los campos estén presentes en todos los eventos.
Implemente controles nulos en su código
Usar valores predeterminados para campos opcionales
Versión API:
La estructura de carga útil del webhook puede variar según la versión de API
Compruebe si necesita actualizar o cambiar de versión
Póngase en contacto con el soporte para obtener documentación de carga útil
Resumen de mejores prácticas
Lista de verificación de implementación de webhook
Seguridad:
✅ Utilice únicamente puntos finales HTTPS
✅ Implementar verificación de firma de webhook
✅ Restringir el acceso con reglas de firewall
✅ Nunca exponga las claves API en el webhook URL
✅ Registre todos los webhooks para auditorías de seguridad
Fiabilidad:
✅ Devuelve el estado 200 inmediatamente (menos de 5 segundos)
✅ Procesar webhooks de forma asincrónica
✅ Implementar idempotencia usando event_id
✅ Utilice la cola de mensajes para un procesamiento sólido
✅ Configurar monitoreo y alertas de fallas
Actuación:
✅ Acuse de recibo rápidamente (devolución 200)
✅ Poner en cola webhooks para procesamiento en segundo plano
✅ Escale horizontalmente si el volumen del webhook es alto
✅ Utilice el almacenamiento en caché cuando corresponda
✅ Optimice las consultas de bases de datos en controladores de webhooks
Pruebas:
✅ Pruebe con webhook.site antes de la producción
✅ Cree webhooks de prueba en un entorno separado
✅ Verificar que la idempotencia funcione correctamente
✅ Pruebe escenarios de error y recuperación
✅ Supervise los webhooks de prueba durante el lanzamiento inicial
Mantenimiento:
✅ Documente todos los webhooks y sus propósitos
✅ Revise los registros de webhooks con regularidad
✅ Desactive los webhooks no utilizados para reducir el ruido
✅ Actualice los puntos finales URL cuando cambie la infraestructura
✅ Auditar las suscripciones a webhooks trimestralmente
Preguntas frecuentes
¿Cuál es la diferencia entre webhooks y la clave API?
La clave API le permite llamar al API de Perkstar para solicitar datos o realizar acciones. Los webhooks envían datos automáticamente cuando ocurren eventos. API = extraes datos. Webhooks = Perkstar le envía datos.
¿Puedo tener varios webhooks con el mismo URL?
Sí, pero normalmente es innecesario. Puede crear un webhook suscrito a varios tipos de eventos. Varios webhooks al mismo URL pueden generar entregas duplicadas si las suscripciones a eventos se superponen.
¿Qué sucede si mi terminal no funciona?
Perkstar reintentará la entrega varias veces durante minutos u horas. Si todos los reintentos fallan, es posible que el webhook se marque como fallido. Deberá volver a habilitarlo y es posible que se pierda eventos durante el tiempo de inactividad. Utilice una cola de mensajes para mayor confiabilidad.
¿Cómo puedo probar webhooks sin afectar los datos de producción?
Utilice una cuenta Perkstar de prueba/sandbox si está disponible, o cree clientes/transacciones de prueba claramente marcados como pruebas. También puede utilizar webhook.site para inspeccionar las cargas útiles antes de crear su punto final.
¿Puedo ver un registro de los webhooks que se enviaron?
Los registros de entrega de webhook pueden estar disponibles en la vista de detalles del webhook, mostrando entregas recientes, marcas de tiempo y estado de éxito/fracaso. Consulte la página de detalles de cada webhook para conocer el historial de entrega.
¿Qué debo hacer si recibo demasiados webhooks?
Cancele la suscripción a tipos de eventos que no necesita o implemente filtros en su punto final para ignorar ciertos eventos. También puede procesar webhooks por lotes en lugar de manejar cada uno individualmente.
¿Puedo usar los URL de localhost para realizar pruebas?
No. Los URL de Localhost (http://localhost:3000) no son de acceso público. Utilice ngrok, webhook.site o implemente en un servicio en la nube con un URL público para realizar pruebas.
¿Cómo sé a qué eventos debo suscribirme?
Comience con los eventos mínimos necesarios para su caso de uso. Punto de partida común: cliente.creado y transacción.completada. Siempre puedes agregar más eventos más adelante a medida que evolucionen las necesidades.
¿Cuál es el tamaño máximo de carga útil para los webhooks? Las cargas útiles de
Webhook suelen ser pequeñas (menos de 10 KB), ya que contienen datos de eventos concisos, no archivos grandes. Si necesita el historial completo del cliente, utilice webhooks para activar llamadas API que obtengan datos detallados.
¿Pueden los webhooks enviar datos a puntos finales internos (red privada)?
No. Los webhooks requieren HTTPS URL de acceso público. Para sistemas internos, utilice un proxy público o una puerta de enlace API que reenvíe a los sistemas internos de forma segura.
¿Con qué rapidez se entregan los webhooks después de un evento? Los webhooks
generalmente se entregan segundos después de que ocurre el evento. El tiempo exacto depende de la carga del sistema, pero se espera una entrega casi en tiempo real en condiciones normales.
¿Qué pasa si recibo un webhook para un evento que no reconozco?
Registre la carga útil completa para su investigación. Perkstar puede agregar nuevos tipos de eventos o es posible que se haya suscrito a eventos accidentalmente. Verifique el campo event_type y compárelo con la documentación.
¿Puedo filtrar webhooks por segmento de clientes o tipo de tarjeta? El filtrado
normalmente no está disponible en el nivel de suscripción del webhook. Recibirá webhooks para todos los eventos de tipos suscritos y deberá filtrar su código de punto final según los datos de carga útil.
¿Cómo actualizo mi webhook URL sin perder la configuración?
Edite el webhook existente, cambie el URL y guárdelo. Se conservan todas las suscripciones y configuraciones de eventos. El nuevo URL recibe inmediatamente futuros webhooks.
¿Están incluidos los webhooks en todos los planes? La disponibilidad del webhook
depende de su plan de suscripción. Consulte la sección de su Plan para ver si se incluyen webhooks y cuántos puede crear. Los planes de nivel superior suelen ofrecer más webhooks. Consejo
: ¿Necesitas más ayuda? Comuníquese con el soporte de Perkstar para solucionar problemas de webhooks, documentación de carga útil, orientación de implementación o preguntas técnicas sobre tipos de eventos y entrega.