¿Qué son los Webhooks?

Los Webhooks son un método de comunicación entre aplicaciones. Se utilizan para que clientes de un servicio web puedan recibir notificaciones en sus propias aplicaciones cuando un evento de interés ocurra. Esto permite que exista una sincronización entre aplicaciones de forma muy sencilla mediante solicitudes POST a través de HTTPs.

¿Qué necesito para usar Webhooks?

Una cuenta de Alegra:
- Esta cuenta será la que quedará asociada a las suscripciones que crees, por lo que estarás recibiendo notificaciones relacionadas a ella.
Una URL propia:
- Deberás contar con una URL propia. Esta URL debe estar preparada para recibir solicitudes POST mediante HTTPs.
- Al momento de crear una suscripción, webhooks enviará una solicitud POST con body vacío a la URL que especifiques. Es necesario que se responda a esta solicitud con código 2XX en menos de 5 segundos, de lo contrario no se creará la suscripción.
- Cada vez que se intente enviar una notificación (mediante una solicitud POST con el contenido del mensaje en el cuerpo) a su URL, esta debe retornar un código 2XX en un plazo máximo de 5 segundos. Si esto no ocurre en 10 intentos consecutivos, su suscripción se eliminará automáticamente.

Formato de Solicitud a Esperar en sus Servidores

New-Client

Nombre	Tipo	Descripción	Ejemplo
id	Integer	Identificador único que representa un contacto específico. La aplicación lo asigna automáticamente.	774
name	Object	Objeto que contiene el nombre del contacto. Puede tener las llaves "firstName", "secondName", "lastName", "secondLastName" ó puede contener solamente "fullname".	`"name": { "firstName": "Primer Nombre", "secondName": "Segundo Nombre", "lastName": "Primer Apellido", "secondLastName": "Segundo Apellido" }`
phonePrimary	String	Número telefónico principal del contacto.	+432432234
phoneSecondary	String	Número telefónico secundario del contacto.	+534234523
mobile	String	Número de celular/móvil.	+443242323123
email	String	Correo electrónico del contacto.	uncorreo@correo.com
type	Array	Indica si el contacto es cliente, proveedor, los dos o ninguno. Las opciones posibles son 'client' y 'provider'.	["client", "provider"]
fax	String	Fax del contacto.	unFax
identification	String	Número de identificación del contacto. Ejemplos: cédula, RFC, RNC, número de pasaporte.	3211233
address	Object	Objeto que contiene la dirección del contacto.	`"address": { "zipCode": "050013", "department": "Antioquia", "country": "Colombia", "address": "Una Dirección", "city": "Abriaquí" }`

{
  "subject": "new-client",
  "message": {
    "client": {
      "id": "774",
      "name": {
        "firstName": "Primer Nombre",
        "secondName": "Segundo Nombre",
        "lastName": "Primer Apellido",
        "secondLastName": "Segundo Apellido"
      },
      "phonePrimary": "+432432234",
      "phoneSecondary": "+534234523",
      "mobile": "+443242323123",
      "email": "uncorreo@correo.com",
      "type": [
        "client",
        "provider"
      ],
      "fax": "unFax",
      "identification": "3211233",
      "address": {
        "zipCode": "050013",
        "department": "Antioquia",
        "country": "Colombia",
        "address": "Una Dirección",
        "city": "Abriaquí"
      }
    }
  }
}

New-Item

Nombre	Tipo	Descripción	Ejemplo
id	String	Identificador único que representa un ítem específico. La aplicación lo asigna automáticamente.	865
name	String	Nombre del ítem.	Un Ítem / S
description	String	Descripción del ítem.	Descripción del Item
reference	String	Referencia del ítem.	423424134213
itemCategory	Object	Objeto que describe la categoría del Ítem.	`"itemCategory": { "id": "19" },`
price	Array	Contiene objetos que representan los precios del Ítem.	`"price": [ { "id": "123", "price": 1 }, { "id": "124", "price": 3 } ],`
inventory	Object	Describe el inventario relacionado al Ítem	`"inventory": { "unit": "unit", "availableQuantity": 1, "unitCost": 1, "initialQuantity": 1, "warehouses": [ { "id": "10" } ] },`
category	Object	Objeto que describe la categoría del ítem.	`"category": { "id": "234" },`
category.id	String	Identificador de la categoría del ítem.	234
tax	Array	Array de impuestos aplicables al ítem.	[]
status	String	Estado del ítem.	active
customFields.id	String	Identificador de los campos personalizados asociados al ítem.	6, 5, 1
type	String	Tipo del ítem.	variant

{
  "subject": "new-item",
  "message": {
    "item": {
      "id": "865",
      "name": "Un Ítem / S",
      "description": "Descripción del Item",
      "reference": "423424134213",
      "itemCategory": {
        "id": "19"
      },
      "price": [
        {
          "id": "123",
          "price": 1
        },
        {
          "id": "124",
          "price": 2
        }
      ],
      "inventory": {
        "unit": "unit",
        "availableQuantity": 1,
        "unitCost": 1,
        "initialQuantity": 1,
        "warehouses": [
          {
            "id": "10"
          }
        ]
      },
      "category": {
        "id": "234"
      },
      "tax": [],
      "status": "active",
      "customFields": [
        {
          "id": "6"
        },
        {
          "id": "5"
        },
        {
          "id": "1"
        }
      ],
      "type": "variant",
      "variantAttributes": null,
      "itemVariants": null,
      "subitems": null
    }
  }
}

New-Invoice

Nombre	Tipo	Descripción	Ejemplo
id	String	Identificador único de la factura.	123
date	String	Fecha de la factura.	2024-06-18
dueDate	String	Fecha de vencimiento de la factura.	2024-06-18
observations	String	Observaciones de la factura. No visibles en el documento impreso o PDF.	Estas son las observaciones de mi factura.
anotation	String	Notas de la factura, visibles en el documento impreso o PDF.	Favor consignar a la cuenta XXXXX.
status	String	Estado de la factura.	open
client.id	String	Identificador del cliente asociado.	123
numberTemplate.id	String	Identificador de la plantilla de numeración de la factura.	123
seller.id	String	Identificador del vendedor asociado.	123
total	Number	Total de la factura.	1190
totalPaid	Number	Total pagado de la factura.	0
balance	Number	Balance restante de la factura.	1190
decimalPrecision	String	Precisión decimal para la factura.	0
estimate.id	String	Identificador de la estimación asociada.	123
costCenter.id	String	Identificador del centro de costos asociado.	123
items.name	String	Nombre del ítem.	cédula digital / Option 2
items.description	String	Descripción del ítem.	Descripción del Item
items.reference	String	Referencia del ítem.	123321
items.price	Number	Precio del ítem.	1000
items.quantity	Number	Cantidad del ítem.	1
items.tax	Array	Array de impuestos aplicables al ítem.	`json "tax": [ { "id": "123" } ]`
items.remission.id	String	Identificador de la remisión asociada al ítem.	123

{
  "subject": "new-invoice",
  "message": {
    "invoice": {
      "id": "123",
      "date": "2024-06-18",
      "dueDate": "2024-06-18",
      "observations": "Notas de facturas de capacitación",
      "anotation": "Notas de facturas de capacitación",
      "status": "open",
      "client": {
        "id": "123"
      },
      "numberTemplate": {
        "id": "123"
      },
      "seller": {
        "id": "123"
      },
      "total": 1190,
      "totalPaid": 0,
      "balance": 1190,
      "decimalPrecision": "0",
      "estimate": {
        "id": "123"
      },
      "costCenter": {
        "id": "123"
      },
      "items": [
        {
          "name": "cédula digital / Option 2",
          "description": "Descripción del Item",
          "reference": "123321",
          "price": 1000,
          "quantity": 1,
          "tax": [
            {
              "id": "123"
            }
          ],
          "remission": {
            "id": "123"
          }
        }
      ]
    }
  }
}