Evento
Un registro de un cambio en un pago, sesión de juego, comprobación KYC, bonificación, perfil de jugador u otro objeto.
Documentación / Webhooks
Webhooks y entrega de eventos
Configure una entrega fiable de estados y eventos entre sistemas: desde la creación del mensaje y la verificación de la firma hasta la confirmación de recepción, el reenvío y la supervisión de errores.
Eventos
estados y cambios
Firma
verificación de autenticidad
Reintentos
reenvío
Supervisión
historial y diagnóstico
Flujo del evento
De la creación a la confirmación
01
Crear un evento
Especifique el identificador, el tipo, la hora, el objeto, el estado y los datos relacionados.
02
Firmar y enviar
Envíe el evento mediante HTTPS con una firma y un tiempo de espera limitado.
03
Confirmar recepción
Después de verificarlo, guarde el evento y devuelva rápidamente una respuesta HTTP correcta.
04
Reintentar en caso de error
Reintente la entrega con intervalos crecientes y conserve los eventos no entregados para su investigación.
Resumen
Un webhook informa de un cambio de estado
El remitente puede reintentar la entrega, por lo que el receptor debe verificar el origen, confirmar la recepción y aplicar cada evento una sola vez.
Confirmación
El receptor devuelve una respuesta HTTP correcta después de verificar y almacenar el evento de forma fiable.
Recuperación
El reenvío y la conciliación ayudan a restaurar los datos después de una falta de disponibilidad temporal de cualquiera de los sistemas.
Estructura del evento
Qué debe contener un evento
Una estructura de mensaje coherente simplifica la verificación, el enrutamiento, la protección frente a duplicados y la compatibilidad con distintos tipos de eventos.
Identificador del evento
Un valor único que utiliza el sistema para reconocer reenvíos y encontrar el historial de procesamiento.
Tipo de evento
Un nombre claro y estable que define el cambio producido y cómo debe procesarse.
Hora de creación
La fecha y hora en que se creó el evento, en el formato y zona horaria acordados.
Objeto relacionado
El tipo y el identificador del pago, jugador, ronda, solicitud, bonificación u otro objeto.
Versión del esquema
Un número de versión ayuda a modificar de forma segura la estructura del mensaje sin interrumpir integraciones activas.
Correlación de la operación
El identificador de la solicitud original, transacción, sesión o cadena de acciones relacionadas.
Contexto
Marca, proyecto, mercado, entorno, proveedor y otros datos necesarios para un enrutamiento correcto.
Datos del evento
El conjunto mínimo de campos necesario para procesar el cambio o realizar una solicitud posterior a la API.
Firma y verificación
Verificación de la autenticidad e integridad del evento
Antes de modificar datos, el receptor verifica la conexión segura, la firma, la hora de creación y el identificador único del evento.
01
Capturar el mensaje sin procesar
Verifique la firma sobre el cuerpo de la solicitud sin procesar antes de cambiar el formato JSON.
02
Comprobar la marca temporal
Rechace la solicitud si la hora del evento queda fuera de la ventana permitida.
03
Verificar la firma
Utilice el secreto acordado y el algoritmo HMAC o de firma digital.
04
Comprobar el identificador
Confirme que el evento no se haya aplicado ya y guarde el resultado de la verificación.
Entrega y reintentos
Respuestas HTTP y reenvío
El remitente debe distinguir entre una recepción correcta, un error temporal y un fallo permanente, mientras que el receptor debe responder con rapidez y sin ambigüedad.
Respuesta HTTP correcta
Confirma que el evento se ha verificado y almacenado de forma fiable para su procesamiento posterior.
Tiempo de espera limitado
No realice un procesamiento prolongado antes de responder al remitente: guarde primero el evento.
Reenvío
Reintente la entrega tras un error temporal de red, falta de disponibilidad o ausencia de respuesta.
Intervalo de reintento creciente
Aumente gradualmente la pausa entre intentos para evitar generar carga adicional.
Cola de eventos no entregados
Una vez agotados todos los intentos, conserve el evento para diagnóstico y gestión manual.
Reenvío manual
Un operador puede reenviar un evento seleccionado sin crear una nueva operación.
Supervisión de la entrega
Controle el número de intentos, las respuestas, el último error y la hora del siguiente envío.
Alertas
Alerte al equipo cuando aumenten los errores, se agoten los reintentos o se acumulen eventos en la cola.
Procesamiento de eventos
Protección frente a duplicados y orden de estados
El receptor no debe depender de una única entrega ni de un orden estricto de los eventos.
Aplicar una sola vez
Guarde el identificador del evento antes de modificar los datos.
Confirme un evento repetido sin otro débito, abono o cambio de estado.
Vincule el evento al objeto y a su estado actual.
Guarde el evento y el cambio de negocio como una única operación coherente.
Orden y vigencia
Compare la marca temporal, el número de secuencia o la versión del evento.
No devuelva un objeto a un estado obsoleto cuando llegue tarde un evento anterior.
Permita únicamente transiciones válidas entre estados.
En caso de duda, solicite el estado actual del objeto mediante la API.
Pruebas
Qué probar antes del lanzamiento
Pruebe la entrega correcta, las firmas no válidas, los duplicados, las respuestas lentas, los eventos fuera de orden y la recuperación tras un fallo.
Firma no válida
Mensaje modificado, clave desconocida, marca temporal caducada y algoritmo no compatible.
Reenvío
El mismo evento llega varias veces antes y después de completar el procesamiento.
Respuesta lenta
El receptor tarda demasiado en responder, la conexión se interrumpe o la confirmación no llega al remitente.
Procesamiento fuera de orden
Un estado final llega antes que uno intermedio y un evento anterior se entrega después de uno más reciente.
Endpoint no disponible
Pruebe errores HTTP 5xx, DNS, TLS, límites de frecuencia y el agotamiento completo de los reintentos.
Historial de entrega
Todos los intentos, respuestas, errores y resultados de reenvío manual deben poder buscarse por identificador de evento.
Lista de comprobación previa al lanzamiento
La entrega en producción se habilita después de verificar la seguridad, la protección frente a duplicados, el reenvío y la supervisión de errores.
Los entornos de pruebas y producción utilizan endpoints y secretos de firma diferentes.
La firma se verifica sobre el mensaje sin procesar junto con su hora de creación.
El identificador del evento se almacena y protege las operaciones frente a ejecuciones múltiples.
El receptor devuelve rápidamente una respuesta HTTP correcta después de almacenar el evento.
Están configurados los reintentos, los intervalos crecientes y el reenvío manual.
El historial de entrega y la búsqueda por identificador están disponibles para el equipo de soporte.
¿Necesita configurar una entrega fiable de eventos?
Facilite la lista de eventos, los endpoints receptores y las reglas de transición de estados. APIACE ayudará a definir la estructura del mensaje, la verificación de firmas, el reenvío y la supervisión de errores.