Cómo funcionan los Webhooks

Los Webhooks proporcionan notificaciones de eventos en tiempo real sobre sus transacciones y actividades de pago. Cuando ocurren eventos a los que se ha suscrito, Getnet envía una petición HTTP POST al endpoint de su Webhook con los detalles del evento.

Este enfoque basado en eventos le permite recibir actualizaciones inmediatas sobre:

• Cambios de estado de la transacción (aprobada, rechazada, capturada, cancelada, reembolsada)
• Eventos de pago (exitosos, fallidos, pendientes)
• Actualizaciones de tarjetas (cambios de caducidad, renovaciones de tokens)
• Y otros eventos relacionados con los pagos

Cómo funciona

En el siguiente diagrama se puede ver una descripción general del flujo de suscripciones y notificaciones de webhooks:

El sistema de Webhook sigue un flujo de trabajo de tres pasos:

1. Configuración

Configure su URL de Webhook y elija qué eventos desea recibir. Utilizando la Webhook Management API de Getnet, usted puede:

• Registrar una URL de notificación
• Suscribirse a tipos de eventos específicos según las necesidades de su negocio
• Configurar la autenticación para su endpoint
• Actualizar o eliminar suscripciones de Webhook existentes

Métodos de autenticación soportados

Al registrar un Webhook, debe elegir uno de los tres métodos de autenticación soportados:

1. Basic Auth (user_credentials) – Getnet incluye una cabecera Authorization: Basic estándar compuesta por el client_id y client_secret que usted proporcione. Configure su endpoint para validar estas credenciales en cada llamada de Webhook.

2. OAuth 2.0 (oauth) – Antes de enviar el Webhook, Getnet solicita un access token del servidor OAuth que usted defina (utilizando el client ID y el secret proporcionados). El token resultante se adjunta a la petición del Webhook como un Bearer token. Utilice esta opción cuando su endpoint espere Bearer tokens OAuth en lugar de credenciales Basic.

3. Token (token) – Getnet utiliza un Bearer token obtenido de la Getnet Authentication API. Este es el mismo token que usted utiliza para autenticar otras peticiones a la API de Getnet. Utilice esta opción cuando su endpoint espere Bearer tokens y desee utilizar el sistema de autenticación de Getnet. Consulte la documentación de Authentication para obtener detalles sobre cómo obtener tokens del endpoint de autenticación.

Elija la opción que coincida con la forma en que el endpoint de su Webhook autentica las llamadas entrantes. El modo oauth ejecuta el flujo completo de client credentials de OAuth 2.0 en su nombre, mientras que el token utiliza un token que ya ha obtenido del endpoint de autenticación de Getnet.

Para la configuración detallada de la autenticación, consulte la documentación Webhooks Reference.

Requisitos del endpoint

El endpoint de su Webhook debe cumplir con estos requisitos:

• Aceptar peticiones HTTP POST
• Utilizar HTTPS con un certificado SSL válido
• Responder con el código de estado HTTP 204 (No Content) cuando el Webhook se reciba con éxito

El endpoint de su Webhook debe utilizar HTTPS con un certificado SSL válido. Lleve un control de las fechas de caducidad de los certificados, ya que los certificados caducados impedirán la entrega del Webhook.

2. Notificación

Cuando ocurre un evento al que está suscrito, la API de Getnet envía automáticamente una petición HTTP POST a su URL configurada, conteniendo todos los datos relevantes del evento. Esto sucede en tiempo real a medida que se procesan las transacciones.

Tipos de eventos disponibles

Getnet ofrece los siguientes tipos de eventos de Webhook que cubren el ciclo de vida completo de la transacción:

Al crear una suscripción de Webhook, usted especifica qué eventos desea recibir. Esto le permite configurar diferentes endpoints de Webhook para diferentes tipos de eventos o gestionar todos los eventos en un solo endpoint.

Para obtener detalles completos sobre cada tipo de evento y sus payloads, consulte la documentación Webhook Payloads.

3. Recepción

Su sistema receptor procesa la notificación y realiza las acciones apropiadas en función de la información recibida. Esto podría incluir:

• Actualizar el estado del pedido en su base de datos
• Desencadenar notificaciones para los clientes
• Iniciar procesos de preparación de pedidos (fulfillment)
• Registrar los resultados de las transacciones para la conciliación
• Actualizar los tokens de las tarjetas cuando cambian los detalles de la tarjeta

Su sistema debe confirmar la recepción respondiendo con un código de estado 204 (No Content). Los eventos se procesan y envían solo al finalizar con éxito para garantizar la integridad de los datos.

Webhook Management API

La Webhook Management API de Getnet proporciona endpoints para gestionar sus suscripciones de Webhook de forma programática. La API le permite:

• Crear suscripciones – Registrar nuevos endpoints de Webhook para eventos específicos
• Listar suscripciones – Recuperar todas sus suscripciones de Webhook
• Eliminar suscripciones – Eliminar las suscripciones de Webhook que ya no necesite
• Ver el historial de eventos – Listar todos los mensajes de Webhook enviados para una suscripción
• Reenviar eventos – Solicitar un reintento de entregas específicas de Webhooks
• Listar eventos suscritos – Ver todos los eventos a los que está suscrito actualmente

Para obtener documentación detallada de los endpoints de la API, incluyendo esquemas de request/response, parámetros y ejemplos, consulte la documentación de la API Reference y Webhooks Reference.

Puede configurar diferentes URLs de Webhook para diferentes entornos (desarrollo, staging, producción) o para diferentes tipos de eventos para organizar mejor su integración.

Fiabilidad y lógica de reintento

Si el endpoint de su Webhook no responde con éxito (código de estado distinto de 204, timeout o error de red), Getnet reintentará automáticamente la entrega del Webhook para garantizar una notificación de eventos fiable.

Payloads del Webhook

Cada evento de Webhook incluye un payload JSON con los detalles de la transacción. La estructura del payload varía según el tipo de evento y el método de pago. Todos los payloads incluyen:

• Identificadores de la transacción (payment_id, order_id, transaction_id)
• Información de importe y divisa
• Códigos de estado y de motivo (reason codes)
• Marcas de tiempo (timestamps) en formato ISO 8601
• Campos específicos del evento

Para obtener la documentación completa de los payloads, incluyendo descripciones de campos, ejemplos para cada tipo de evento y campos específicos del método de pago, consulte la documentación de Webhook Payloads.

Próximos pasos

Ahora que comprende cómo funcionan los Webhooks, está listo para integrarlos en su aplicación:

1. Revisar las opciones de autenticación – Elija el método de autenticación que coincida con los requisitos de su endpoint. Consulte Webhooks Reference para obtener detalles.

2. Explorar los eventos disponibles – Revise los tipos de eventos y determine cuáles necesita. Consulte Webhooks Reference para obtener la lista completa.

3. Configurar su endpoint – Asegúrese de que el endpoint de su Webhook cumple los requisitos y puede manejar los payloads esperados.

4. Crear suscripciones – Utilice la Webhook Management API para crear suscripciones. Consulte la API Reference para obtener detalles del endpoint.

5. Revisar las estructuras del payload – Familiarícese con la estructura del payload para cada tipo de evento que recibirá. Consulte la documentación Webhook Payloads para obtener todos los detalles.