Aller au contenu
Sections de la documentation

Console des webhooks

L'onglet Webhooks de la page Developers configure les webhooks : chaque webhook envoie les events que vous choisissez, pour les expéditions que vous choisissez, vers une URL qui vous appartient, dès que Safecube les détecte. L'onglet liste vos webhooks, les crée en un clic ou étape par étape, et affiche, modifie ou supprime chacun d'eux. Le format des events et la façon de les recevoir sont décrits dans le guide Premiers pas avec les webhooks de la documentation de l'API.

Qui peut ouvrir Webhooks

GesteRôle minimumPlan
Ouvrir l'onglet Webhooks et voir la listeAdminTous les plans
Créer, modifier, dupliquer ou supprimer un webhookAdminTous les plans

Un Editor ou un Viewer ne voit pas Developers dans la barre latérale, et un lien vers /api/webhooks le mène à la page d'accès refusé.

Ouvrir l'onglet Webhooks

  1. Sélectionnez Developers dans la barre latérale.
  2. Sélectionnez l'onglet Webhooks.

L'adresse https://app.safecube.ai/api/webhooks ouvre directement l'onglet. Le haut de l'onglet indique « Setup your webhook environment to receive real-time updates on your shipments. » et contient :

  • Use our playground, un lien vers le playground Svix, une page gratuite qui vous donne une URL de test pour recevoir des webhooks avant que votre propre URL soit prête ;
  • Open Svix dashboard, un lien vers le portail Svix de votre espace de travail, affiché seulement une fois le portail créé ;
  • Fast alert set up et Custom alert, les deux façons de créer un webhook.

Liste des webhooks

ColonneCe qu'elle affiche
Webhook URLL'URL qui reçoit les events. Sélectionnez-la pour la copier.
EventsLe nombre d'events que le webhook envoie.
ShipmentsLe nombre d'expéditions que le webhook suit.
StatusActive, ou Disabled quand le webhook n'envoie rien.
Last updateLa date de la dernière modification du webhook.

Sélectionnez un en-tête de colonne pour trier la liste sur cette colonne. La liste affiche 10 webhooks par page, avec une pagination au-delà. Sur chaque ligne, le bouton en forme d'œil, Webhook details, ouvre le webhook, et le menu … contient Duplicate config et Delete.

Avant votre premier webhook, la liste indique No webhooks. Quand la liste ne peut pas être chargée, le toast « Failed to load webhook endpoints. Please try again later. » s'affiche.

Configurer un webhook en un clic

  1. Sélectionnez Fast alert set up. La boîte de dialogue One click webhook setup s'ouvre.
  2. Dans Enter endpoint URL, saisissez votre URL après https://. L'URL doit commencer par https://.
  3. Cochez Add demo shipment to my webhook pour recevoir des events de test de l'expédition de démo ZZZZ0000000.
  4. Sélectionnez Create my webhook.

Le webhook envoie les 4 events par défaut, shipment.added.to.endpoint, shipment.any.change, shipment.auto.removed et shipment.in.error. Il ne suit aucune expédition, ou seulement l'expédition de démo : aucune des expéditions déjà suivies dans votre espace de travail n'est ajoutée. Ajoutez ensuite vos expéditions avec Edit webhook.

En cas de succès, la boîte de dialogue se ferme, le toast « Webhook endpoint created successfully. » s'affiche et le webhook arrive en tête de la liste. En cas d'échec, la boîte de dialogue indique Webhook creation failed, avec Contact us et Try again.

Créer une alerte personnalisée

Custom alert ouvre une page en trois étapes : Configuration, Add shipments et Events. Passez de l'une à l'autre avec Previous et Next, ou sélectionnez une étape en haut de la page. Back revient à la liste.

  1. Configuration : saisissez l'URL dans Enter endpoint URL ; elle doit commencer par https://. Activez Optional information pour régler les options listées dans la section suivante. Next reste désactivé tant que l'URL ou les métadonnées sont invalides.
  2. Add shipments : saisissez le Shipment number, gardez Auto Detect ou choisissez la compagnie dans Type or select carrier, choisissez le Shipment type, CT (conteneur), BL (connaissement) ou BK (booking), puis sélectionnez +. Chaque expédition rejoint le tableau Tracked shipments. Cochez Add a demo shipment to test your webhook setup pour ajouter l'expédition de démo.
  3. Events : choisissez des events dans Search events. Les 4 events par défaut sont déjà sélectionnés ; chaque event sélectionné apparaît sous Tracked events, avec une croix pour le retirer.
  4. Sélectionnez Submit.

Sans expédition, Warning! indique « You are about to create a webhook with no tracked shipment you will not receive any alerts with these settings. Do you confirm creation ? ». Sélectionnez Create webhook pour continuer, ou Cancel.

En cas de succès, la page indique Your webhook is ready ! et prévient que les expéditions suivies peuvent mettre quelques minutes à être traitées ; View all webhooks revient à la liste. En cas d'échec, elle indique Webhook Creation failed, avec Contact us et Update selection, qui revient à la première étape.

Informations optionnelles

ChampCe qu'il règle
DisabledTrue arrête toute livraison vers l'URL, et la liste affiche Disabled. False garde le webhook actif.
Rate limit, UID, Version, DescriptionOptions de l'endpoint, décrites dans la référence de création d'un endpoint.
MetadataDes données à vous rattachées au webhook, en JSON. Sinon la page indique « Metadata must be in JSON format ».

Choisir les events

Search events regroupe les events sous Port of discharge, Port of loading, Post POD, Pre POL, Shipment et Transshipment. Chaque event affiche son nom technique, comme shipment.any.change ; survolez-le pour lire ce qu'il signifie. Le sens de chaque event et les données qu'il envoie sont décrits dans le guide Events de webhook.

Consulter un webhook

Sélectionnez le bouton en forme d'œil d'une ligne. La page de détail affiche :

  • Configuration : la Webhook URL, l'ID du webhook et son Secret, chacun avec un bouton de copie, et les Optional information ;
  • Tracked events ;
  • Tracked shipments, avec Shipment number, Sealine et Shipment type.

Le Secret est affiché en clair : votre serveur s'en sert pour vérifier qu'un webhook vient bien de Safecube, comme décrit dans Premiers pas avec les webhooks.

Modifier un webhook

  1. Ouvrez le webhook et sélectionnez Edit webhook.
  2. Changez l'URL ou les informations optionnelles, ajoutez ou retirez des events sous Tracked events, et ajoutez ou retirez des expéditions sous Tracked shipments.
  3. Sélectionnez Save.

La page quitte aussitôt le mode édition, puis les toasts « Webhook endpoint updated successfully. » et « Webhook shipment updated successfully. » confirment la modification. Un échec affiche « Failed to update webhook endpoint. Please try again later. » ou « Failed to update webhook shipment. Please try again later. ». La page n'a pas de bouton Cancel ; Back permet de la quitter.

Pour arrêter un webhook sans le supprimer, réglez Disabled sur True sous Optional information, puis sélectionnez Save.

Dupliquer un webhook

  1. Ouvrez le menu … d'une ligne et sélectionnez Duplicate config.
  2. Custom alert s'ouvre avec les informations optionnelles, les events et les expéditions du webhook, mais sans URL ni UID.
  3. Saisissez la nouvelle URL, parcourez les étapes et sélectionnez Submit.

Supprimer un webhook

  1. Ouvrez le menu … d'une ligne et sélectionnez Delete.
  2. La boîte de dialogue Delete webhook affiche l'URL et indique « This action cannot be undone. All associated data will be permanently deleted. ».
  3. Sélectionnez Delete.

Le toast « Webhook endpoint deleted successfully. » s'affiche et la ligne quitte la liste. En cas d'échec, la boîte de dialogue affiche Server error avec Retry. Un webhook ne peut pas être supprimé depuis sa page de détail.

Tester un webhook

  • Utilisez une URL du playground Svix, depuis Use our playground, comme URL du webhook pour voir les events dans votre navigateur.
  • Ajoutez l'expédition de démo ZZZZ0000000 au webhook, à sa création ou avec Edit webhook, pour recevoir des events de test.

Les autres façons d'envoyer des events de test sont décrites dans Tester votre endpoint de webhook.

Limites

  • L'onglet n'affiche aucun journal de livraison, ne renvoie pas un event en échec et ne renouvelle pas le secret : cela se fait dans le portail Svix, depuis Open Svix dashboard, ou par l'API, comme décrit dans Détecter et rattraper les échecs de webhook.
  • L'onglet n'affiche aucun payload : les données envoyées par chaque event sont décrites dans Events de webhook.
  • Fast alert set up n'ajoute au webhook aucune de vos expéditions suivies.
  • Un ID de webhook qui n'existe pas ouvre une page de détail vide, sans message d'erreur.
  • Le renouvellement de la clé d'API de l'espace de travail n'arrête pas les webhooks existants : ils continuent de livrer, comme décrit dans Identifiants d'API.