Saltar al contenido principal

Webhooks

¿Qué son los webhooks?​

Los webhooks permiten suscribirte a ciertos eventos que occuren a nivel de recurso en la api de a3factura. Por ejemplo, puedes suscribirte a un webhook de clientes para que cuando desde la aplicación o vía API se dé de alta un nuevo cliente, se envíe una petición POST a tu servidor que te avisará que se ha producido un evento de alta.

Los recursos de la API permiten suscribirse a notificaciones de cambio, siendo principalmente Updated, Created y Deleted.

Recursos que permiten configurar webhooks​

Te detallamos la relación de recursos y acciones que permiten suscripción:

Recurso
Customer.Created
Customer.Deleted
Customer.Updated
Product.Created
Product.Deleted
Product.Updated
Supplier.Created
Supplier.Deleted
Supplier.Updated
Representative.Created
Representative.Deleted
Representative.Updated
Contact.Created
Contact.Deleted
Contact.Updated
Due.Created
Due.Deleted
Due.Updated
SaleInvoice.Created
SaleInvoice.Deleted
SaleInvoice.Updated
PurchaseInvoice.Created
PurchaseInvoice.Deleted
PurchaseInvoice.Updated
SaleOffer.Created
SaleOffer.Deleted
SaleOffer.Updated
SaleOrder.Created
SaleOrder.Deleted
SaleOrder.Updated
PurchaseOrder.Created
PurchaseOrder.Deleted
PurchaseOrder.Updated
SaleDeliveryNote.Created
SaleDeliveryNote.Deleted
SaleDeliveryNote.Updated
PurchaseDeliveryNote.Created
PurchaseDeliveryNote.Deleted
PurchaseDeliveryNote.Updated
Bank.Created
Bank.Deleted
Bank.Updated
IncomeType.Created
IncomeType.Deleted
IncomeType.Updated
ExpenseType.Created
ExpenseType.Deleted
ExpenseType.Updated
CompanyData.Updated
CompanySettings.Updated

Configurando tu servidor​

Antes de poder suscribirte a un webhook, es necesario que configures tu servidor para recibir las peticiones HTTP POST que se van a realizar. Algunos aspectos básicos que esperamos de tu endpoint son:

  1. Debe utilizar HTTPS sobre el puerto estándar 443
  2. Tiene que responder a la petición HTTP POST antes de 5 segundos con una respuesta HTTP 2xx.
  3. Los headers de respuesta no deben contener cookies.
  4. Si la firma es inválida, deberás devolver un error HTTP 401.

Suscribirme a un webhook​

Para crear un nuevo webhook deberás enviar una petición POST al endpoint api/webhooks con el siguiente body:

  • uri: Tiene que tener el formato https://{baseaddress}/api/webhooks/incoming/a3Factura donde {baseaddress} es la url desde donde se está haciendo la petición.
  • entity: entidad al que se quiere subscribir.
  • action: tipo de acción al que se quiere subscribir. (Created, Updated, Deleted).
  • secret: string para indentificar quién hace la llamada.
  • isPaused: indica si se quiere pausar o no la subscripcion.
  • applicationName: nombre de la aplicación receptora.
  • description: descripción del hook.
POST /a3factura/api/webhooks HTTP/1.1
Host: a3api.wolterskluwer.es
Ocp-Apim-Subscription-Key: 2kxwf5rb7ffb65dd5
Authorization: Bearer eyJhbG ...
Content-Type: application/json
Content-Length: 376
{
  "uri": "http://{baseaddress}/api/webhooks/incoming/a3Factura",
  "entity": "Supplier",
  "action": "Updated",
  "secret": "12345678901234567890123456789012",
  "isPaused": false,
  "applicationName": "Test",
  "descripion": "Test"
}
Atención

En este momento, nuestra plataforma de webhooks comprobará si el servidor al que quiere enviar los eventos está escuchando, por lo que realizará una petición GET a la URI proporcionada, agregando el parámetro ?echo=GUID al final de la URL. El valor de este GUID debe ser devuelto como respuesta en el body-response de la petición GET para que la suscripción sea efectiva.

Notificación del webhook​

Cuando se produce un evento, la notificación enviada a tu servidor es el siguiente objeto:

public class WebHookNotificationCommand
{
    public string Entity { get; set; }
    public string EntityId { get; set; }
    public string TenantId { get; set; }
    public string User { get; set; }
    public List<AttributeChanged> Changes { get; set; }
}

public class AttributeChanged
{
    public string Name { get; set; }
    public string Value { get; set; }
}

GET All webhooks​

Para obtener todos los webhook a los que estás suscrito, puedes enviar una petición GET al endpoint /api/webhooks

GET /a3factura/api/webhooks HTTP/1.1
Host: a3api.wolterskluwer.es
Ocp-Apim-Subscription-Key: 2kxwf5rb7ffb65dd5
Authorization: Bearer eyJhbG...
Content-Type: application/json

Unsubscribe de un webhook​

Para eliminar la suscripción a un webhook, deberás enviar una petición DELETE al endpoint /api/webhooks/{id}

DELETE /a3factura/api/webhooks/{id} HTTP/1.1
Host: a3api.wolterskluwer.es
Ocp-Apim-Subscription-Key: 2kxwf5rb7ffb65dd5
Authorization: Bearer eyJhbG...
Content-Type: application/json
Última actualización en