Skip to main content
Esta guía explica cómo puedes usar webhooks para recibir notificaciones automáticas de Confío cada vez que ocurran eventos importantes, como un cambio en el estado de un pago. Implementar webhooks es fundamental para mantener tu plataforma sincronizada y automatizar tus flujos de trabajo.

​
Descripción General del Proceso

Cuando ocurre un evento en tu cuenta de Confío, como la actualización del estado de un pago, Confío envía una solicitud POST a un endpoint que tú configuras. Esta solicitud contiene toda la información relevante sobre el evento. Tu plataforma debe:
  1. Recibir la notificación del webhook en un endpoint público.
  2. Verificar que la solicitud proviene de Confío (usando el token de autorización).
  3. Procesar la información del evento y actualizar el estado correspondiente en tu sistema.
  4. Responder con un código de estado 200 OK para confirmar la recepción.

​
Requisitos Previos

Para manejar webhooks de Confío, necesitarás:
  1. Un endpoint HTTPS en tu servidor que sea accesible públicamente.
  2. Haber contactado a tu gerente de cuenta de Confío para:
    • Registrar la URL de tu endpoint de webhooks
    • Obtener el PARTNER_ACCESS_TOKEN que Confío usará para autenticarse en tus webhooks
    • Configurar los eventos que deseas recibir
  3. Lógica en tu backend para verificar y procesar las solicitudes entrantes.
Nota: No necesitas ser partner de Confío para recibir webhooks. Cualquier desarrollador puede registrar un endpoint de webhooks contactando a su gerente de cuenta.

​
Seguridad de los Webhooks

Para asegurar que las notificaciones son genuinas y provienen de Confío, debes verificar el encabezado Authorization en cada solicitud entrante.
  • Authorization: Bearer <PARTNER_ACCESS_TOKEN>
Este es el mismo token que recibiste durante el proceso de handshake. Cualquier solicitud que no contenga este encabezado o cuyo token no sea válido debe ser rechazada.

​
Eventos de Webhook

Confío envía diferentes tipos de eventos, cada uno identificado por el encabezado X-Confio-Event y el campo event en el payload.

​
Cambio de Estado del Pago

  • Event: payment.statusChanged
  • Cuándo se envía: Cuando el estado de un pago es actualizado.
  • Payload: Ejemplo real
{
  "event": "payment.statusChanged",
  "data": {
    "name": "stores/01JXJVXE6R10GB6MX6SSPW40AM/payments/01K4V4HTSRQA4N7R6VQQSQXY7W",
    "url": "https://checkout.confiopagos.com/p/01K4V4HTSRQA4N7R6VQQSQXY7W",
    "amountCents": 8000000,
    "currencyCode": "COP",
    "title": "Dos Memorias Ram",
    "description": "Dual channel de memoria ram de 16gb cada una gamer RGB a 4600mhz marca viper DDr4",
    "buyer": {
      "firstName": "Juan",
      "phoneNumber": "+573053568988",
      "email": "[email protected]"
    },
    "status": "UNDER_REVIEW",
    "organization": "organizations/01JXJVXE5240N8BZVPMWF91576",
    "redirectUri": "https://tu-tienda.com/ordenes/123",
    "disableBuyerNotification": false,
    "paymentType": "PRODUCT",
    "enabledPaymentMethods": ["CARD", "PSE"],
    "correlationId": "ord_12345"
  },
  "environment": "PRODUCTION",
  "timestamp": 1757553509,
  "signature": {
    "properties": [
      "name",
      "correlationId",
      "amountCents",
      "currencyCode",
      "status"
    ],
    "checksum": "sha256=..."
  }
}

​
Cambio de Estado del Intento de Pago

  • Event: paymentAttempt.statusChanged
  • Cuándo se envía: Cuando el estado de un intento de pago es actualizado.
  • Payload: Ejemplo real
{
  "event": "paymentAttempt.statusChanged",
  "data": {
    "name": "stores/01JXJVXE6R10GB6MX6SSPW40AM/payments/01K4V4HTSRQA4N7R6VQQSQXY7W/attempts/01K4V4KT2T2HFBP9WJECW5373X",
    "createTime": "2025-09-11T01:00:37.337Z",
    "method": "PSE",
    "payer": {
      "name": "users/01JXJVXE3SNHKVCEY2E8SR89D0",
      "firstName": "Juan",
      "lastName": "Perez",
      "document": "132656565",
      "documentType": "CC",
      "phoneNumber": "+57305595686",
      "email": "[email protected]",
      "ip": "0.0.0.0"
    },
    "status": "SUCCEEDED",
    "correlationId": "ord_12345",
    "errorMessage": ""
  },
  "environment": "PRODUCTION",
  "timestamp": 1757552495,
  "signature": {
    "properties": ["name", "correlationId", "method", "status"],
    "checksum": "sha256=..."
  }
}

​
Mejores Prácticas

  1. Responde Rápidamente: Tu endpoint debe responder con un código 200 lo más rápido posible. Para operaciones que toman tiempo, procésalas de forma asíncrona en segundo plano para evitar timeouts.
  2. Manejo de Reintentos: Confío reintentará enviar un webhook si no recibe una respuesta exitosa (2xx). Tu sistema debe ser idempotente para manejar notificaciones duplicadas sin causar problemas.
  3. Registra las Notificaciones: Mantén un registro de los webhooks recibidos. Esto es invaluable para depurar problemas y tener una auditoría de los eventos.

​
Recursos Adicionales