Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cobrix.co/llms.txt

Use this file to discover all available pages before exploring further.

Cuando creas un pago con callbackUrl, Cobrix envía un HTTP POST a esa URL al completarse el pago.
Los webhooks de la External Payments API son fire-and-forget: las entregas fallidas se registran pero no se reintentan automáticamente. Usa Get Payment como fuente de verdad para operaciones críticas.

​
Payload

{
  "eventType": "external_payment.completed",
  "resourceType": "external_payment",
  "companyId": "company-uuid",
  "payload": {
    "id": "payment-uuid",
    "status": "completed",
    "amountMinor": 15000,
    "currency": "VES",
    "invoiceId": "invoice-uuid",
    "paymentId": "internal-payment-uuid"
  }
}
CampoDescripción
eventTypeSiempre external_payment.completed (por ahora)
resourceTypeexternal_payment
companyIdUUID de la empresa dueña del pago
payload.idUUID del pago externo (usar para dedup)

​
Eventos disponibles

EventoDisparador
external_payment.completedEl pago se procesó con éxito

​
Handler recomendado

import express from 'express'

const router = express.Router()

router.post('/cobrix', express.json(), async (req, res) => {
  const event = req.body

  // 1. Responde rápido (< 5s)
  res.status(200).json({ received: true })

  // 2. Procesa en background, con deduplicación
  setImmediate(async () => {
    const { id, status, invoiceId, paymentId } = event.payload

    // Dedup por payment id
    if (await db.webhookEvents.exists(id)) return
    await db.webhookEvents.create({ id, processedAt: new Date() })

    // 3. Confirma con GET antes de operar
    const fresh = await cobrix.getPayment(id)
    if (fresh.status !== 'completed') return

    await orderService.markAsPaid(fresh.externalReference, { paymentId })
  })
})

​
Recomendaciones

Responde 200 rápido

En menos de 5 segundos, antes de procesar.

Procesa asíncrono

Encola el evento y hazlo fuera del handler HTTP.

Deduplica por `payload.id`

Puedes recibir el mismo evento más de una vez.

Valida con GET

GET /payments/{id} es la fuente de verdad.

​
Troubleshooting

​
No llega el webhook

  1. Verifica que callbackUrl sea HTTPS y accesible desde internet.
  2. Revisa el campo webhookAttempts en el registro del pago (vía GET /payments/{id}).
  3. Si tu endpoint estaba caído, recuerda que no hay reintento automático — usa el GET para recuperar el estado.

​
Respuestas lentas

Cobrix espera pocos segundos por una respuesta. Si tu handler tarda, mueve la lógica a una cola (Redis, SQS, etc.) y responde 200 de inmediato.