Saltar al contenido principal

Webhooks

Overview​

Sistema de webhooks para notificar eventos del sistema a clientes externos mediante HTTP requests asíncronos.

La confiugracion del webhook se puede hacer por el Dashboard -> Integraciones en https://dashboard.cachicamo.app/store/integrations

  • Configuración por acción: Cada acción puede tener hasta 3 webhooks configurados
  • Reintentos automáticos: Hasta 5 intentos con 1 hora de espera entre cada uno

Documentación para Clientes (Webhooks que Recibirán)​

Eventos Disponibles​

Los siguientes eventos pueden ser configurados para recibir notificaciones:

1. document.created​

Se dispara cuando se crea un documento (factura, nota de débito, nota de crédito, etc.).

Payload:

{
  "id": "invoice-uuid-here",
  "document_type": "INVOICE",
  "action": "document.created",
  "event_at": "2024-01-15T10:30:00Z"
}

Campos:

  • id (string): UUID del documento creado

  • document_type (string): Tipo de documento. Valores posibles:

    • INVOICE: Factura

    • DEBIT_NOTE: Nota de débito

    • CREDIT_NOTE: Nota de crédito (refund)

    • PROVIDER_INVOICE: Factura de proveedor

    • PROVIDER_DEBIT_NOTE: Nota de débito de proveedor

    • PROVIDER_CREDIT_NOTE: Nota de crédito de proveedor

    • QUOTE: Cotización

  • action (string): Nombre del evento

  • event_at (string): Fecha y hora del evento en formato ISO 8601

Nota: Solo se envía el ID del documento, no el objeto completo. El cliente debe consultar el documento usando el ID si necesita más información.

2. document.updated​

Se dispara cuando se actualiza un documento.

Payload:

{
  "id": "invoice-uuid-here",
  "document_type": "INVOICE",
  "action": "document.updated",
  "event_at": "2024-01-15T10:35:00Z"
}

3. product.created​

Se dispara cuando se crea un nuevo producto.

Payload:

{
  "payload": {
    "uuid": "product-uuid-here",
    "name": "Producto Ejemplo",
    // ....
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "action": "product.created",
  "event_at": "2024-01-15T10:30:00Z"
}

Nota: Se envía el objeto completo del producto con todos sus campos.

4. product.updated​

Se dispara cuando se actualiza un producto o cuando se crea/actualiza un precio del producto.

Payload:

{
  "payload": {
    "uuid": "product-uuid-here",
    "name": "Producto Actualizado",
    // ....
  },
  "action": "product.updated",
  "event_at": "2024-01-15T10:35:00Z"
}

Nota: Se envía el objeto completo del producto actualizado.

5. stock.updated​

Se dispara cuando se actualiza el stock de un producto (inventario).

Payload:

{
  "payload": {
    "user_uuid": "user-uuid-here",
    "store_uuid": "store-uuid-here",
    "product_uuid": "product-uuid-here",
    "quantity_billable": 100.0,
    "quantity_available": 95.0,
    "quantity_locked": 5.0,
    "quantity_transit": 0.0,
    "warehouse_location": "A-1-2",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z"
  },
  "action": "stock.updated",
  "event_at": "2024-01-15T10:35:00Z"
}

6. document_to_pay.created​

Se dispara cuando se crea un documento por pagar (cuenta por cobrar o por pagar).

Payload:

{
  "payload": {
    "uuid": "document-to-pay-uuid",
    "document_uuid": "invoice-uuid-here",
    "document_type": "INVOICE",
    "status": "PENDING",
    "user_uuid": "user-uuid-here",
    "store_uuid": "store-uuid-here",
    "customer_uuid": "customer-uuid-here",
    "description": "Factura pendiente de pago",
    "currency_uuid": "currency-uuid-here",
    "amount_pending": 100000,
    "original_amount": 100000,
    "amount_payed": 0,
    "is_collect": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "action": "document_to_pay.created",
  "event_at": "2024-01-15T10:30:00Z"
}

7. document_to_pay.payment​

Se dispara cuando se registra un pago parcial o total de un documento por pagar.

Payload:

{
  "payload": {
    "uuid": "payment-uuid-here",
    "document_to_pay_uuid": "document-to-pay-uuid",
    "payment_method_uuid": "payment-method-uuid",
    "currency_uuid": "currency-uuid-here",
    "document_total_payment": 50000,
    "origin_total_payment": 50000,
    "created_at": "2024-01-15T10:35:00Z"
  },
  "action": "document_to_pay.payment",
  "event_at": "2024-01-15T10:35:00Z"
}

8. document_to_pay.payed​

Se dispara cuando un documento por pagar se marca como completamente pagado.

Payload:

{
  "payload": {
    "uuid": "document-to-pay-uuid",
    "document_uuid": "invoice-uuid-here",
    "document_type": "INVOICE",
    "status": "PAID",
    "amount_pending": 0,
    "amount_payed": 100000,
    "payed_at": "2024-01-15T10:40:00Z"
  },
  "action": "document_to_pay.payed",
  "event_at": "2024-01-15T10:40:00Z"
}

9. retained.reference_assigned​

Se dispara cuando se asigna un reference a una retención de factura de venta.

Payload:

{
  "payload": {
    "uuid": "retained-uuid-here",
    "tax_uuid": "tax-uuid-here",
    "invoice_uuid": "invoice-uuid-here",
    "reference": "REF-001",
    "status": "ASSIGNED",
    "retained_type": "WITHHELD_BY_SUPPLIER",
    "retained_amount": 10000,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z"
  },
  "action": "retained.reference_assigned",
  "event_at": "2024-01-15T10:35:00Z"
}

10. retained.group_created​

Se dispara cuando se crea un comprobante de retención para facturas de compra.

Payload:

{
  "payload": {
    "uuid": "retained-uuid-here",
    "tax_uuid": "tax-uuid-here",
    "invoice_uuid": "invoice-uuid-here",
    "taxes_retained_group_uuid": "group-uuid-here",
    "reference": "GRP-001",
    "status": "ASSIGNED",
    "retained_type": "WITHHELD_BY_ME",
    "retained_amount": 10000,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z"
  },
  "action": "retained.group_created",
  "event_at": "2024-01-15T10:35:00Z"
}

11. retained.group_cancelled​

Se dispara cuando se anula un comprobante de retención.

Payload:

{
  "payload": {
    "uuid": "retained-uuid-here",
    "tax_uuid": "tax-uuid-here",
    "invoice_uuid": "invoice-uuid-here",
    "taxes_retained_group_uuid": "group-uuid-here",
    "status": "CANCELLED",
    "cancel_reason": "Error en el comprobante",
    "cancelled_at": "2024-01-15T10:40:00Z",
    "retained_amount": 10000
  },
  "action": "retained.group_cancelled",
  "event_at": "2024-01-15T10:40:00Z"
}

12. retained.cancelled​

Se dispara cuando se anula una retención individual.

Payload:

{
  "payload": {
    "uuid": "retained-uuid-here",
    "tax_uuid": "tax-uuid-here",
    "invoice_uuid": "invoice-uuid-here",
    "status": "CANCELLED",
    "cancel_reason": "Error en la retención",
    "cancelled_at": "2024-01-15T10:40:00Z",
    "retained_amount": 10000
  },
  "action": "retained.cancelled",
  "event_at": "2024-01-15T10:40:00Z"
}

Formato del Mensaje HTTP​

Cuando se recibe un webhook, el sistema enviará una petición HTTP con:

  • Método: El configurado en method (típicamente POST)

  • URL: La configurada en destination

  • Headers: Los headers personalizados configurados. Nota: El sistema siempre establece Content-Type: application/json automáticamente, ignorando cualquier valor de Content-Type que se configure en los headers personalizados.

  • Body: El payload JSON con payload, action y event_at

Ejemplo de petición HTTP:

POST https://example.com/webhook HTTP/1.1
Content-Type: application/json
X-Custom-Header: value

{
  "payload": {
    "uuid": "product-uuid-here",
    "name": "Producto Ejemplo",
    ...
  },
  "action": "product.created",
  "event_at": "2024-01-15T10:30:00Z"
}

Características del Sistema​

Reintentos Automáticos​

  • Si un webhook falla, se reintenta automáticamente hasta 5 veces

  • Intervalo entre reintentos: 1 hora

  • Estados de destino:

    • pending: Pendiente de envío

    • retry: Falló y será reintentado

    • sent: Enviado exitosamente

    • failed: Falló después de 5 intentos