Configurez les clés API et les webhooks

Peut ne pas être activé

API & Webhooks n'est peut-être pas disponible dans votre espace de travail ou votre offre. Si cette option n'apparaît pas, contactez l'administrateur de votre espace de travail.

Les clés API donnent à une intégration un accès programmatique aux API de lecture de votre compte, et les webhooks poussent les notifications d’événements vers vos propres points de terminaison HTTPS. Ensemble, ils vous permettent de connecter Belrald Assets au reste de vos systèmes.

Tout se trouve dans Settings → API & Webhooks, réparti sur deux onglets : API keys et Webhooks. Les propriétaires et les administrateurs peuvent créer et gérer les deux ; les responsables voient la page en lecture seule, signalée par une puce Read-only. Si la fonctionnalité n’est pas activée pour votre compte, la page affiche une carte expliquant que l’API publique n’est pas activée — contactez votre administrateur pour l’activer.

Créez une clé API

1. Ouvrez l’onglet API keys et sélectionnez New API key.
2. Name — donnez à la clé un libellé reconnaissable, tel que CI pipeline (120 caractères ou moins).
3. Environment — choisissez Live ou Test. Ceci est défini à la création et ne peut pas être modifié par la suite.
4. Scopes — cochez les autorisations dont la clé a besoin. Seules read:workorders et read:assets correspondent aujourd’hui à un point de terminaison actif et sont cochées par défaut. Les quatre autres portées sont marquées no endpoint yet — vous pouvez les accorder, mais elles ne font rien tant que l’API publique d’écriture n’est pas livrée.
5. Sélectionnez Create key.

Attention

Le secret complet n’est affiché qu’une seule fois, dans la boîte de dialogue API key created. Copiez-le immédiatement — Belrald Assets ne le stocke jamais et ne peut pas vous le montrer à nouveau. Si vous le perdez, renouvelez la clé pour en obtenir un nouveau.

La clé apparaît alors dans la liste avec son nom, une pastille d’environnement, la clé masquée (prefix…last4 — jamais le secret complet), ses portées et sa dernière utilisation (Never used tant qu’aucune intégration n’a appelé l’API avec elle).

Renouvelez ou révoquez une clé

Ouvrez le menu ⋯ sur la ligne d’une clé pour accéder à ses actions.

• Edit modifie le nom et les portées de la clé. L’environnement reste fixe.
• Rotate génère un nouveau secret, affiché une seule fois. Votre secret précédent continue de fonctionner pendant 24 heures, ce qui vous permet de mettre à jour votre intégration sans interruption.
• Revoke désactive la clé. Toute intégration qui l’utilise cesse de fonctionner immédiatement, et ceci ne peut pas être annulé — le bouton vous demande de cliquer à nouveau pour confirmer.

Créez un webhook

1. Ouvrez l’onglet Webhooks et sélectionnez New webhook.
2. Name — un libellé reconnaissable, tel que Ops relay.
3. Endpoint URL — la destination des livraisons. Elle doit être une URL HTTPS publique.
4. Events — choisissez les événements auxquels vous abonner dans la liste groupée et consultable (Work orders, Assets, Maintenance requests, Preventive maintenance, Meters, Contracts, Inventory, Quotes, SLA, Certifications, Payments et Workflow). Sélectionnez-en au moins un.
5. Sélectionnez Create webhook.

Attention

Le signing secret (whsec_…) n’est affiché qu’une seule fois, dans la boîte de dialogue Webhook created. Copiez-le maintenant — vous ne le reverrez plus. Utilisez-le pour vérifier que les livraisons proviennent bien de Belrald Assets.

La boîte de dialogue de création contient également une recette repliable Verify deliveries que vous pouvez copier. Le webhook apparaît ensuite dans la liste avec un point d’état, son URL, un décompte d’événements, l’heure de la dernière livraison assortie d’un marqueur de succès ou d’échec, et une pastille d’état Active, Disabled ou Paused.

Vérifiez chaque livraison

Chaque livraison porte un en-tête X-Belrald-Signature de la forme t=<unix>,v1=<hmac_sha256_hex>. Avant de faire confiance à une charge utile :

1. Lisez l’horodatage t et la signature v1 dans l’en-tête.
2. Construisez la charge signée comme {t}.{rawBody} — l’horodatage, un point, puis le corps brut exact de la requête.
3. Calculez hmac_sha256(signing_secret, signed_payload) et comparez-le à v1 avec une comparaison à temps constant.

Le corps de la requête est un JSON de la forme { id, type, occurredAt, data }.

Gérez et surveillez un webhook

Ouvrez le menu ⋯ sur la ligne d’un webhook pour accéder à ses actions.

• Edit modifie le nom, l’URL et les événements et, sur un webhook existant, bascule son état Active.
• Send test met en file d’attente une livraison de test synthétique. Consultez le journal de livraison pour voir le résultat ; il n’y a pas de réponse en ligne.
• Delivery log affiche les 100 livraisons les plus récentes, de la plus récente à la plus ancienne. Chaque ligne indique le type d’événement, le nombre de tentatives, un statut HTTP, l’extrait de réponse et un statut pending, success, failed ou exhausted. Le journal est en lecture seule.
• Rotate secret émet un nouveau signing secret, affiché une seule fois.
• Enable / Disable active ou désactive les livraisons.
• Delete supprime le webhook. Il cesse de recevoir des événements, et ceci ne peut pas être annulé.

Attention

Le renouvellement du signing secret est une bascule instantanée — il n’y a aucune période de grâce. Le webhook cesse de fonctionner jusqu’à ce que vous mettiez à jour votre vérificateur avec le nouveau secret ; faites-le donc dans la même session.

Note

Belrald Assets désactive automatiquement un webhook après plusieurs échecs de livraison. Un webhook désactivé affiche une note recent failures sur sa ligne ; corrigez votre point de terminaison, puis réactivez-le avec Enable.