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}}

Attention

Le mécanisme de WebHook est implémenté via la « File d’attente des travaux » (JobQueue), qui n’est pas autorisée aux administrateurs délégués.

Les modifications apportées par un administrateur délégué ne seront transmises via le webhook que lors d’une modification ultérieure par un utilisateur disposant d’une licence (voir Dynamics 365 Business Central and Power Automate Connector: create, modify, delete triggers things to know. – Stefano Demiliani).