Configurar e inspeccionar Webhooks

Los webhooks son llamadas HTTP (callbacks) que nuestro servidor hace al tuyo cuando ocurre un evento importante de manera asíncrona (ej. una cotización se aprobó o se pagó).

Registrar un endpoint

Para recibir webhooks, expón una ruta POST en tu servidor (ej. https://api.tuempresa.com/webhooks/cord).

1. Activa el Modo desarrollador en Tu cuenta › Preferencias. Aparece la píldora Desarrolladores en la esquina inferior derecha: ábrela (o pulsa W) y entra a la pestaña Webhooks del Workbench (/app?wb=webhooks).
2. Pulsa Agregar endpoint y elige los eventos: Todos los eventos, una familia completa o eventos sueltos. El buscador filtra los 41 eventos por nombre.
3. Escribe tu URL, pública y con HTTPS, y pulsa Crear endpoint. El secreto de firma se muestra una sola vez: guárdalo.

Eventos disponibles

Cord emite eventos del ciclo de vida de la cotización y, por separado, de la factura como objeto propio (ver Facturación y la API):

• quote.sent — se envió al cliente.
• quote.viewed — el cliente la abrió.
• quote.approved — el cliente la aprobó.
• quote.rejected — el cliente la rechazó.
• quote.updated — se modificó y reenvió.
• quote.expired — venció sin respuesta.
• quote.deleted — se eliminó un borrador.
• quote.paid — se pagó por completo.
• payment.partial — se recibió un anticipo, saldo o cuota sin cubrir el total.
• payment.failed — falló un cobro recurrente.
• invoice.issued, invoice.stamped — se emitió la factura de una cotización: comercial fuera de México o CFDI timbrado.
• invoice.finalized, invoice.sent, invoice.paid, invoice.payment_failed, invoice.voided, invoice.marked_uncollectible, invoice.overdue — ciclo de vida de una factura creada como recurso propio vía /api/v1/facturas.
• quote.created, quote.approval_requested, quote.approval_decided, quote.comment_added — se creó una cotización, se pidió o decidió una aprobación interna, o alguien escribió en la conversación.
• client.created, client.updated, client.deleted, product.created, product.updated, product.deleted — cambios en tu directorio de clientes y en tu catálogo.
• task.created, task.completed, promise.created, promise.kept, promise.broken — tareas y promesas de pago.
• dispute.created, dispute.closed, refund.succeeded, refund.failed, payout.paid, payout.failed, account.updated — contracargos, reembolsos, depósitos y cambios en tu cuenta de cobros.

Con Todos los eventos, el endpoint recibe también los que Cord agregue después.

El cuerpo es JSON: { "id": "evt_...", "event": "quote.paid", "created_at": "...", "data": { "id", "folio", "status", "moneda", "total", "cliente", "cliente_id", "link_publico" } }. El id del evento es estable a través de reintentos y de un reenvío manual desde el Workbench — úsalo para deduplicar del lado de tu servidor.

Verificación de firma

Valida siempre la firma para asegurar que el evento viene de Cord. Cada entrega incluye X-Cord-Signature-V1 (con timestamp, protección anti-repetición) y, por compatibilidad, la firma heredada X-Cord-Signature (sin timestamp). El nombre del evento viaja en X-Cord-Event y su id estable en X-Cord-Event-Id/Idempotency-Key. Si usas Node, constructEvent de @flouviahq/node la valida por ti; si prefieres verificarlo a mano en cualquier lenguaje, ve el código de verificación.

Reintentos e inspección

El botón Probar de cada endpoint manda una entrega de prueba: ping o cualquier evento al que esté suscrito, con datos de ejemplo y "test": true en el primer nivel del cuerpo.

Al desplegar un endpoint ves su log de entregas (estado, latencia y respuesta de cada intento) y, al abrir una, lo que Cord envió y lo que respondió tu servidor. Si una entrega falla, la reintentas desde ahí o reenvías el evento desde la pestaña Eventos. El historial de entregas, reintentar y reenviar son parte del plan Profesional o superior.