Conecta otro sistema con webhooks

Un webhook es un aviso automático: cada vez que pasa algo en Klopi —la DIAN valida una factura, entra un pago, se crea un contacto—, Klopi le envía los datos a una dirección de internet que tú defines. Así tu tienda en línea, tu ERP o el sistema que te hizo un desarrollador se entera en el momento, sin que nadie copie datos a mano.

Casi siempre, quien te pide «un webhook» es la persona que desarrolla tu otro sistema. Tú creas el webhook en Klopi y le pasas dos cosas: qué eventos llegan y el secreto de firma. La documentación completa para esa persona está en Desarrolladores → Documentación.

Antes de empezar

• El adicional Desarrolladores activo, que se agrega sobre el plan Klopi. Con él aparece Desarrolladores en Configuración → Más ajustes. Si no lo ves, revisa cómo agregar un adicional.
• Ser Propietario o Administrador.
• La dirección a la que Klopi debe avisar, que te da quien desarrolla tu otro sistema. Tiene que empezar por https:// y ser la dirección final: Klopi no sigue redirecciones.

Crea un webhook

Puedes tener hasta 10 webhooks. Cada tarjeta tiene un interruptor para apagarlo sin borrarlo, Editar para cambiar la dirección o los eventos, y Eliminar, que te pide confirmar antes de borrarlo. Al eliminarlo se borra también su historial de entregas.

Los eventos disponibles

Evento	Cuándo se envía
contact.created	Se creó un contacto (desde la app, una integración o una importación)
contact.updated	Cambió algún dato de un contacto
contact.deleted	Se eliminó un contacto
product.created	Se creó un producto o servicio
product.updated	Cambió un producto o servicio
invoice.created	Se creó un borrador de factura
invoice.issued	La DIAN validó una factura
invoice.rejected	La DIAN rechazó una factura
invoice.paid	Una factura quedó pagada del todo
invoice.credited	Una nota crédito devolvió una parte de una factura
invoice.cancelled	Una factura quedó anulada: notas crédito devolvieron todo su valor
invoice.draft_discarded	Se eliminó o descartó un borrador de factura
credit_note.issued	La DIAN validó una nota crédito
debit_note.issued	La DIAN validó una nota débito
payment.received	Entró un pago de un cliente
quote.accepted	Un cliente aceptó una cotización
quote.rejected	Un cliente rechazó una cotización
expense.created	Se registró un gasto

Los documentos soporte y la nómina electrónica no se publican por webhook, ni los empleados como contactos.

Revisa las entregas

En la tarjeta del webhook, haz clic en Entregas. Cada fila muestra el evento, la fecha, la respuesta del otro sistema (por ejemplo, HTTP 200), el tiempo y cuántos intentos llevó. Ábrela para ver el cuerpo exacto que se envió y lo que respondió el otro sistema. Si una entrega no llegó, haz clic en Reenviar. Las entregas se guardan 90 días.

Para quien desarrolla el otro sistema

Klopi hace un POST con un cuerpo JSON así:

{
  "id": "2b4d6f80-…",
  "type": "payment.received",
  "api_version": "2026-10-01",
  "created_at": "2026-10-01T10:02:19-05:00",
  "source": "app",
  "company_id": "1111…",
  "data": { "object": { "id": "…", "object": "payment", "amount": "394800.00", "invoice": { "id": "…", "number": "FEV124" } } }
}

data.object es el mismo objeto que responde la API de Klopi para ese recurso. source dice quién hizo el cambio: app, api, import o system. Los valores en pesos llegan como texto con dos decimales. Cada petición trae estas cabeceras:

Cabecera	Qué es
X-Klopi-Event	El id del evento. Es el mismo en todos los reintentos: úsalo para no procesarlo dos veces
X-Klopi-Event-Type	El tipo de evento
X-Klopi-Delivery	El id de esta entrega
X-Klopi-Timestamp	La hora del envío, en segundos Unix
X-Klopi-Signature	sha256= seguido del HMAC-SHA256, en hexadecimal, de "<timestamp>.<cuerpo>" con el secreto de firma

Para comprobar que el aviso viene de Klopi, calcula el HMAC-SHA256 del texto X-Klopi-Timestamp + . + el cuerpo tal como llegó, con el secreto de firma, y compáralo con la cabecera en tiempo constante. Rechaza los avisos con una hora de más de 5 minutos: así nadie puede reenviar uno que haya capturado. La documentación trae el código listo en Python, Node.js y PHP.

Responde con un código 2xx en menos de 10 segundos. Klopi no sigue redirecciones y no envía avisos a direcciones de redes internas.

Qué pasa después

• Cada evento se envía después de que queda guardado en Klopi. Si algo se deshace antes de guardarse, no sale ningún aviso.
• Si el otro sistema no responde o responde con un error, Klopi lo reintenta cinco veces más, con el mismo id de evento: a 1 minuto, 5 minutos, 30 minutos, 2 horas y 12 horas. Después, la entrega queda fallida y la puedes Reenviar a mano.
• Si 20 entregas seguidas fallan, Klopi apaga el webhook, la tarjeta dice por qué y te avisa en las notificaciones. Cuando el otro sistema esté arreglado, envía un evento de prueba y vuelve a prender el interruptor.
• Mientras un webhook está apagado, lo que iba a enviarse se omite: al prenderlo solo llegan los eventos nuevos. Las entregas omitidas se pueden Reenviar una por una.
• Un problema con un webhook nunca frena a Klopi. La factura, el pago o el contacto se guardan igual, aunque el aviso no llegue.

Preguntas frecuentes

¿Puedo enviar datos a Klopi?

Sí, con la API de Klopi y una API key: crear contactos, productos, facturas y pagos desde tu sistema. Lee Conecta tu sistema con la API de Klopi.

¿Cómo se entera mi otro sistema de que anulé una factura?

Una factura emitida no se borra: se anula con una nota crédito por su valor. Cuando la DIAN valida esa nota, llega credit_note.issued y, sobre la factura, invoice.cancelled. Si la nota devolvió solo una parte, llega invoice.credited con el nuevo saldo. Una factura anulada no envía invoice.paid: su saldo quedó en cero, pero nadie pagó.

¿Qué hago si alguien más conoce el secreto de firma?

En la tarjeta del webhook haz clic en Generar otro. El secreto anterior deja de firmar en ese momento: pásale el nuevo al otro sistema para que no rechace los avisos.

¿Por qué el evento de prueba sale fallido?

Porque el otro sistema no respondió con un código 2xx en 10 segundos. En Entregas ves la respuesta que dio, por ejemplo HTTP 404 si la dirección está mal escrita. El evento de prueba no se reintenta solo.