Implementar un receptor

Un webhook es una petición HTTP POST que Cobrix envía a tu servidor cuando ocurre algo relevante. Tu receptor debe validar que la petición proviene de Cobrix, guardar el evento y responder rápido.

Antes de programar

Una URL pública con HTTPS para sandbox

El secreto del webhook guardado como variable de entorno

El evento webhook.test habilitado para la prueba inicial

Acceso al cuerpo crudo de la petición, antes de convertirlo a objeto

Configura el canal correcto

En Cobrix abre Configuración → Integraciones → Webhooks. La misma pantalla reúne ambos canales, pero los presenta en secciones separadas para que el contrato y las acciones de cada endpoint sean explícitos:

Canal visible	Úsalo para	Eventos	Confirmación
Webhook general	Pagos, checkout, cobranza, clientes y suscripciones	Selección individual o todos los eventos generales	Cualquier HTTP `2xx`
API de documentos · `cobrix_invoice_v1`	Ciclo de vida de documentos creados por la API compatible	`invoice.created`, `invoice.paid` e `invoice.canceled`, administrados por Cobrix	HTTP `200` exacto

Ambos canales pueden apuntar a la misma URL HTTPS, pero cada uno conserva su propio secreto y su propia fórmula de firma. Los endpoints de documentos aparecen individualmente por partner y ambiente; el drawer muestra ese vínculo, el protocolo y los nombres técnicos antes de guardar.

Campo	Qué colocar
URL	La ruta pública de tu receptor, por ejemplo `https://api.tu-sistema.com/webhooks/cobrix`
Secreto	Un valor largo y aleatorio. No lo envíes en el payload ni lo registres en logs.
Eventos	En el canal general selecciona únicamente los eventos que tu sistema procesa. El canal de documentos se actualiza automáticamente desde el backend.
Estado	Debe estar habilitado para recibir entregas.

Usa endpoint y secreto distintos para sandbox y producción. El ambiente se determina por la aplicación Cobrix desde la que configuraste el webhook.

collection_document.cancelled pertenece al webhook general. invoice.canceled pertenece a cobrix_invoice_v1. Aunque ambos representan una anulación, no comparten envelope ni fórmula de firma.

Configurar, administrar o eliminar un endpoint

La vista Endpoints muestra únicamente configuraciones existentes. Para crear un endpoint de documentos, selecciona Configurar endpoint público en la parte superior y elige dentro del panel el partner que todavía no tiene una URL configurada. Cada endpoint configurado incluye sus propias acciones:

Acción	Webhook general	API de documentos
Editar URL y estado	Sí	Sí, dentro del contrato del partner y ambiente indicados
Elegir eventos	Sí	No; Cobrix incorpora automáticamente los eventos `invoice.*` compatibles
Eliminar endpoint	Sí	Sí
Rotar o consultar el secreto	Según la acción disponible en el webhook	El secreto se establece al configurar nuevamente el endpoint

Al eliminar un endpoint de documentos, Cobrix deja de enviarle futuras entregas invoice.* y retira su fila de la tabla. La eliminación no borra el partner, sus llaves API ni los documentos existentes: el partner vuelve a estar disponible en Configurar endpoint público. Si lo configuras nuevamente, debes establecer un secreto nuevo en el receptor.

La diferencia no es de permisos ni de calidad de servicio. El webhook general es una suscripción configurable para varios dominios; cobrix_invoice_v1 es un contrato de compatibilidad dedicado, único por partner y ambiente, con eventos administrados por Cobrix.

Flujo de una entrega

Cobrix construye el evento

El webhook general usa un envelope con id, event y data. El canal de documentos usa {invoice, event}.

Cobrix firma los bytes

La firma HMAC-SHA256 se calcula sobre el cuerpo JSON exacto. Los eventos generales incluyen también un timestamp.

Tu endpoint verifica

Lee el cuerpo crudo, calcula la firma esperada y compárala en tiempo constante.

Tu endpoint deduplica

Para el canal general guarda payload.id. Para documentos usa event.type + invoice.id. Si la clave ya existe, no repitas la acción.

Tu endpoint responde

Encola el trabajo y devuelve una respuesta exitosa inmediatamente. Para cobrix_invoice_v1 debe ser HTTP 200 exacto.

Receptor mínimo en Node.js

import crypto from 'node:crypto'
import express from 'express'

const app = express()

// express.raw conserva exactamente los bytes firmados por Cobrix.
app.post('/webhooks/cobrix', express.raw({ type: 'application/json' }), async (req, res) => {
  const rawBody = req.body
  const signatureHeader = req.get('X-Cobrix-Signature') ?? ''
  const parts = Object.fromEntries(signatureHeader.split(',').map(part => part.split('=')))
  const timestamp = Number(parts.t)

  if (!Number.isFinite(timestamp) || Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300) {
    return res.status(401).json({ error: 'stale_webhook' })
  }

  const expected = crypto
    .createHmac('sha256', process.env.COBRIX_WEBHOOK_SECRET)
    .update(`${timestamp}.${rawBody.toString('utf8')}`)
    .digest()
  const received = Buffer.from(parts.v1 ?? '', 'hex')

  if (received.length !== expected.length || !crypto.timingSafeEqual(received, expected)) {
    return res.status(401).json({ error: 'invalid_signature' })
  }

  const payload = JSON.parse(rawBody.toString('utf8'))
  await saveEventIfNew(payload.id, payload.event, payload)
  await enqueueWebhook(payload.id)

  return res.status(200).json({ received: true })
})

No uses express.json() antes de esta ruta. Si el framework vuelve a serializar el objeto, espacios, orden o escapes pueden cambiar y la firma dejará de coincidir.

Implementar un receptor

Antes de programar

Configura el canal correcto

Configurar, administrar o eliminar un endpoint

Flujo de una entrega

Receptor mínimo en Node.js

Qué evento procesar primero

Confirmar un pago

Probar conectividad

​Antes de programar

​Configura el canal correcto

​Configurar, administrar o eliminar un endpoint

​Flujo de una entrega

​Receptor mínimo en Node.js

​Qué evento procesar primero

Confirmar un pago

Probar conectividad

Antes de programar

Configura el canal correcto

Configurar, administrar o eliminar un endpoint

Flujo de una entrega

Receptor mínimo en Node.js

Qué evento procesar primero