API, webhook

Il s’agit d’un mécanisme standard, implémenté dans Dynamics NAV/Business Central depuis la version 2017, qui facilite la synchronisation des données entre applications.

Ainsi par exemple, si Business Central est connecté à un site e-commerce, les mises à jour apportées aux articles pourront être mises en ligne immédiatement.

Principe

• l’application cliente (ici le site de e-commerce) souscrit un abonnement à ces mises à jour.

• à chaque mise à jour, Business Central lui envoie une notification succincte (entité concernée, Id de l’élément mis à jour, et type de mise à jour : création, modification, suppression).

• l’application cliente invoque alors l’API concernée pour accéder aux informations de cet élément.

Liens utiles (en anglais)

Working with Webhooks – Dynamics NAV | Microsoft Docs

Webhooks with Dynamics 365 Business Central – Stefano Demiliani

How to test Business Central webhooks – Kauffmann @ Dynamics 365 Business Central

Shopify and Business Central WebHooks continuous synchronisation: a smart replication with your e-commerce. – Yet another www.business-central.blog (wordpress.com)

Souscription

POST https://api.businesscentral.dynamics.com/v2.0/{{tenant}}/development/api/v1.0/subscriptions

Avec en Body :

{
  « notificationUrl »: « https://{{applicationEndPoint}}« ,
  « resource »: « companies({{companyId}})/items »,
  « clientState »: « SuperSecretValue123! »
}

La réponse donne un subscriptionId qu’il faut immédiatement renvoyer avec le token (étape dite de handshaking, similaire à l’appairage de deux appareils bluetooth par exemple).

L’abonnement est alors actif pour 3 jours et devra être renouvelé entretemps :

PATCH https://api.businesscentral.dynamics.com/v2.0/{{tenant}}/development/api/v1.0/subscriptions({{subscriptionId}})

Notification

L’application abonnée reçoit une notification à chaque mise à jour de l’entité concernée.

Exemple :

{
  subscriptionId: ‘64388bc336fe4c658c51f1c716ae4d9c’,
  clientState: ‘SuperSecretValue123!’,
  expirationDateTime: ‘2021-02-05T21:19:01Z’,
  resource:’companies(2f8e9e69-78f1-ea11-bb69-000d3a210b63)/items(792d3a99-78f1-ea11-bb69-000d3a210b63)’,
  changeType: ‘updated’,
  lastModifiedDateTime: ‘2021-02-02T21:26:21.42Z’
}

Vous noterez que l’élément est identifié par son ‘systemId’ (ici 792d3a99-78f1-ea11-bb69-000d3a210b63) et non par son « N° » habituel (susceptible d’être renuméroté).

Divers

Liste des souscriptions actives :

GET https://api.businesscentral.dynamics.com/v2.0/{{tenant}}/{{environment}}/api/v1.0/subscriptions

Résiliation :

La requête ci-dessus retourne les 2 informations nécessaires (@odata.etag et le subscriptionId) ci-après.

« @odata.etag »: « W/\ »JzQ0O0VJYnRzZUkrTm01QU5qNEthTldEcmljRTNTNmVEN3d5MW44YmdmSWZPQUk9MTswMDsn\ » », 
« subscriptionId »: « 55b3e2db5f1843c4a478c71e16282702 »,

Définir en Header If-Match reprenant le @odata.etag en y remplaçant \ » par « , soit pour le cas ci-dessus (attention au  » qui subsiste à la fin) :

W/ »JzQ0O0VJYnRzZUkrTm01QU5qNEthTldEcmljRTNTNmVEN3d5MW44YmdmSWZPQUk9MTswMDsn »

DELETE https://api.businesscentral.dynamics.com/v2.0/{{tenant}}/{{environment}}/api/v1.0/subscriptions({{subscriptionId}}