Webhooks en tiempo real, para todos los eventos de tu negocio

Los webhooks de COPE entregan todos los eventos relevantes de tu negocio directamente a tu sistema en tiempo real – firmados, fiables y con herramientas completas para desarrolladores.

📄 Documentación completa: [Webhooks overview - COPE]

Qué incluyen los webhooks de COPE

Endpoints exclusivamente HTTPS
Firma HMAC-SHA256 con protección anti-replay
Estándar de payload CloudEvents 1.0
Reintentos automáticos con backoff
Replay de eventos durante 90 días

Flujo:
COPE → Evento → Tu endpoint (webhook)

Ejemplo: payload de webhook en tiempo real

http

POST /your-endpoint HTTP/1.1 Content-Type: application/json Cope-Signature: t=1717499231,v1=a8c7b9...  {   "specversion": "1.0",   "type": "payment.sale.succeeded",   "source": "cope-payments",   "id": "evt_01HK9YJF...",   "time": "2026-06-04T13:42:11Z",   "subject": "ord_8s7xV2K",   "data": {     "order_id": "ord_8s7xV2K",     "business_uuid": "biz_a1b2c3",     "amount_total": 49700,     "currency": "USD"   } }

Eventos a los que puedes suscribirte

Los webhooks (una notificación automática en tiempo real enviada de COPE a tu sistema) son configurables por endpoint y por tipo de evento - tú decides si recibes todo o solo eventos específicos.

Eventos a los que puedes suscribirte

Los webhooks son configurables por endpoint y por tipo de evento – tú decides si recibes todo o solo eventos específicos.

Eventos de carrito
cart.created · cart.line.added · cart.line.updated · cart.line.removed · cart.buyer_identity.set · cart.currency.changed · cart.abandoned

Eventos de checkout
checkout.created · checkout.cancelled · checkout.expired

Eventos de pedido
order.created · order.completed · order.failed

Eventos de pago
payment.sale.succeeded · payment.sale.failed · payment.refund.created · payment.refund.reversed

Disputas y contracargos
payment.dispute.opened · payment.dispute.won · payment.dispute.lost · payment.dispute.counter_fee.created · payment.chargeback.created · payment.chargeback.reversed

Pagos a proveedores
payout.transfer.initiated · payout.transfer.completed

Ticketing
ticketing.event.published · ticketing.check_in.created · ticketing.ticket.issued · ticketing.ticket.voided · ticketing.ticket.reissued

Ciclo de vida del webhook
webhook.endpoint.created · webhook.endpoint.updated · webhook.endpoint.auto_disabled

Cada evento ilustra el caso de uso.

CloudEvents 1.0 – un estándar que tu stack ya entiende

Todos los payloads de webhooks siguen CloudEvents 1.0 – un envelope consistente y predecible para cada evento.

Campo	Significado
`specversion`	Siempre `1.0`
`type`	Tipo de evento (p. ej. `payment.sale.succeeded`)
`source`	Servicio origen
`id`	ID único del evento
`time`	Marca de tiempo en formato RFC3339
`subject`	Recurso principal (p. ej. ID de pedido)
`data`	Payload específico del evento

Importante – idempotencia: Los webhooks se entregan at-least-once. Los eventos pueden llegar más de una vez y el orden no está garantizado. Deduplica siempre usando source + id.

Seguridad – HMAC-SHA256 con anti-replay

Cada webhook está firmado para que puedas verificar que proviene realmente de COPE.

Cope-Signature: t=timestamp,v1=hmac_signature

La firma se basa en timestamp.rawBody (HMAC-SHA256). Los eventos con más de 5 minutos de antigüedad se rechazan automáticamente.

Ejemplo (Node.js):

import crypto from 'crypto';  function verifyCopeWebhook(rawBody, signatureHeader, secret) {   const parts = signatureHeader.split(',').reduce((acc, p) => {     const [k, v] = p.split('=');     acc[k] = v;     return acc;   }, {});    const timestamp = parseInt(parts.t, 10);   const signature = parts.v1;    const ageSeconds = Math.floor(Date.now() / 1000) - timestamp;   if (ageSeconds > 300) return false;    const expected = crypto     .createHmac('sha256', secret)     .update(`${timestamp}.${rawBody}`)     .digest('hex');    return crypto.timingSafeEqual(     Buffer.from(expected, 'hex'),     Buffer.from(signature, 'hex')   ); }

Notas importantes:

Cada endpoint (la dirección URL a la que COPE envía datos) tiene su propio signing secret
El secret solo se muestra una vez al crearlo
La rotación requiere actualmente crear un nuevo endpoint
Nunca uses el secret en código frontend

Entrega y fiabilidad

Calendario de reintentos:

Intento	Intervalo
1.er intento	30 segundos
2.º intento	5 minutos
3.er intento	30 minutos
4.º intento	2 horas
5.º intento	12 horas
Máximo	6 intentos

5xx / timeout → reintento
4xx → sin reintento (el endpoint rechaza el evento)
Fallos persistentes → desactivación automática del endpoint

Cuando un endpoint se desactiva automáticamente, se envía un evento webhook.endpoint.auto_disabled y recibes una notificación por correo.

Garantía de entrega: At-least-once · Sin orden garantizado · La idempotencia es tu responsabilidad (source + id)

Herramientas para desarrolladores

Eventos de prueba – lanza eventos sintéticos firmados exactamente igual que los reales
Replay – reenvía eventos individuales o en bulk desde un momento dado, hasta 90 días de historial
Logs de entrega – código de estado, tiempo de respuesta, contador de reintentos y timestamp por entrega
Estadísticas de endpoint – tasa de éxito, latencia p99, filtro por tipo de evento

Disponible ahora vs. roadmap

● Disponible ahora:
Webhooks solo HTTPS · Firma HMAC-SHA256 + anti-replay · CloudEvents 1.0 · Sistema de reintentos con backoff · Entrega at-least-once · Cobertura de eventos (carrito, checkout, pedidos, pagos, reembolsos, disputas, payouts) · API de gestión de endpoints · Eventos de prueba · Replay (90 días) · Logs y estadísticas de entrega

○ Roadmap:
Rotación de secrets con periodo de gracia · Redacción de PII por endpoint · Conectores nativos para Zapier / Make / n8n · Entrega exactly-once / ordenada