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 endpoint

En Cobrix abre Configuración → Integraciones → Webhooks, crea un endpoint y define:

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	Selecciona únicamente los eventos que tu sistema procesa.
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.

Flujo de una entrega

Cobrix construye el evento

El payload incluye un identificador, el tipo de evento, la fecha, la versión y los datos específicos.

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

Guarda payload.id con una restricción única. Si ya existe, no repitas la acción.

Tu endpoint responde

Encola el trabajo y devuelve 200 inmediatamente. El procesamiento financiero o de negocio continúa en segundo plano.

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 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 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 endpoint

Flujo de una entrega

Receptor mínimo en Node.js

Qué evento procesar primero