Premiers pas avec les webhooks
Les webhooks Safecube, aussi appelés alertes de suivi de conteneurs, envoient les events de suivi vers une URL publique qui vous appartient dès que Safecube les détecte, sans que vous ayez à interroger la Container Tracking API. Une configuration de webhook a deux parties : un endpoint, c'est-à-dire l'URL qui reçoit les events et la liste des events auxquels elle est abonnée, et les expéditions suivies pour cet endpoint. Les webhooks se configurent de deux façons : depuis l'application web Safecube, ou par la Webhooks API.
Configurer les webhooks depuis l'application web Safecube
Les réglages des webhooks se trouvent dans l'application web Safecube à l'adresse https://app.safecube.ai/api/webhooks : ouvrez Developers dans la barre latérale, puis l'onglet Webhooks. Seuls un Admin ou un Owner de l'espace de travail peuvent l'ouvrir. La page propose deux façons de créer un webhook. Chaque écran de l'onglet est décrit dans Console des webhooks.
Option 1 : Fast alert set up
Fast alert set up crée un webhook à partir de sa seule URL :
- le webhook s'abonne aux quatre events par défaut
shipment.added.to.endpoint,shipment.any.change,shipment.auto.removedetshipment.in.error; - il ne suit aucune expédition, ou seulement l'expédition de démo
ZZZZ0000000: les expéditions déjà suivies par votre compte ne sont pas ajoutées.
Les events et les expéditions suivis se modifient ensuite ; les events se choisissent parmi ceux listés sur la page Events de webhook.
Option 2 : Custom alert
Custom alert donne accès à tous les réglages du webhook :
- les réglages avancés, comme la description, les métadonnées et la limite de débit de l'endpoint ;
- les expéditions précises à suivre ;
- les events précis auxquels s'abonner.
Configurer les webhooks par l'API
La Webhooks API est servie à l'adresse https://api.sinay.ai/webhook/api/v1. Chaque requête est authentifiée par votre clé d'API Safecube dans l'en-tête API_KEY, comme décrit sur la page Authentification.
Créer un endpoint
Un endpoint se définit par trois paramètres principaux :
- L'URL publique où vous voulez recevoir les events. Pour tester les webhooks avant que votre propre URL soit prête, utilisez une URL du Svix Playground.
- Un secret, qui vous permet de vérifier que les events viennent de Safecube. Laissez-le vide et Safecube le génère ; définir votre propre secret est possible mais déconseillé.
- Les events que vous voulez recevoir, listés sur la page Events de webhook. Les events recommandés sont
shipment.added.to.endpoint,shipment.in.error,shipment.any.changeetshipment.auto.removed.
Seule l'URL est obligatoire pour créer un endpoint ; les autres paramètres se modifient plus tard. Créez l'endpoint avec POST /endpoint :
curl -X POST "https://api.sinay.ai/webhook/api/v1/endpoint" \
-H "API_KEY: $SAFECUBE_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"description": "An example endpoint name",
"url": "https://example.com/webhook/",
"filterTypes": ["container.discharge.at.final.pod"]
}'
L'API répond 201 Created, et la réponse contient l'ID de l'endpoint (ep_…). Conservez-le : l'ajout d'expéditions l'exige. Pour le retrouver plus tard, listez vos endpoints avec GET /endpoint.
Ajouter des expéditions à suivre
Une fois l'endpoint créé, ajoutez les expéditions à suivre avec POST /easy-shipment-asynchronous. Le corps de la requête est indexé par ID d'endpoint, et chaque expédition demande :
- un numéro d'expédition : un numéro de conteneur, ou un numéro de booking ou de connaissement ;
- la compagnie maritime (
sealine, code SCAC) : facultative pour un numéro de conteneur, obligatoire avec un numéro de booking ou de connaissement.
curl -X POST "https://api.sinay.ai/webhook/api/v1/easy-shipment-asynchronous" \
-H "API_KEY: $SAFECUBE_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"ep_2hMa1FHBpIQGkZ0QOOvYire4WJu": {
"shipments": [{ "number": "TIIU4429132" }]
}
}'
Chaque expédition déclenche ensuite un event shipment.added.to.endpoint ou shipment.in.error. La page Ajouter des expéditions explique comment réagir à chacun.
Pour tester les webhooks avec une expédition de démo, ajoutez le conteneur ZZZZ0000000 sans compagnie maritime : il envoie toutes les 6 heures chacun des events auxquels votre endpoint est abonné.
Intégrer vos webhooks
Envoyer un webhook d'exemple
POST /endpoint/{endpoint_id}/send-example envoie à tout moment un event d'exemple à votre endpoint. Indiquez le type d'event dans le corps de la requête :
curl -X POST "https://api.sinay.ai/webhook/api/v1/endpoint/{endpoint_id}/send-example" \
-H "API_KEY: $SAFECUBE_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{ "eventType": "vessel.departure.from.transhipment_port" }'
La page Tester votre endpoint de webhook liste toutes les façons d'envoyer des events de test.
Suivre vos webhooks dans le Svix Playground
Quand l'URL de l'endpoint est une URL du Svix Playground, comme https://play.svix.com/in/{your_url_id}, les webhooks qui lui sont envoyés se consultent dans n'importe quel navigateur à l'adresse https://play.svix.com/view/{your_url_id}.
Vérifier la signature des webhooks
Chaque webhook envoyé à votre endpoint est signé avec une clé propre à cet endpoint. Récupérez le secret de l'endpoint avec GET /endpoint/{endpoint_id}/secret : la réponse contient une clé encodée en base64, qui vérifie les payloads que Safecube envoie à l'endpoint.
curl "https://api.sinay.ai/webhook/api/v1/endpoint/{endpoint_id}/secret" \
-H "API_KEY: $SAFECUBE_API_KEY" \
-H "Accept: application/json"
Safecube envoie les webhooks par Svix : le guide de vérification de Svix détaille comment vérifier un payload avec cette clé.
Surveiller vos webhooks
Toutes les informations de suivi sur les endpoints, les messages et les events sont disponibles par les endpoints de la Webhooks API, comme GET /endpoint/{endpoint_id}/stats. La page Détecter et rattraper les échecs de webhook montre comment détecter et renvoyer les webhooks en échec.
Les mêmes informations s'affichent aussi dans un tableau de bord de suivi. GET /dashboard renvoie votre propre lien vers ce tableau de bord :
curl "https://api.sinay.ai/webhook/api/v1/dashboard" \
-H "API_KEY: $SAFECUBE_API_KEY" \
-H "Accept: application/json"