# Console des webhooks

> L'onglet Webhooks de la page Developers permet aux Admins et aux Owners de créer, consulter, modifier, désactiver et supprimer les webhooks qui envoient les events des expéditions de Safecube vers leur propre URL, en un clic ou étape par étape.

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](/fr/api/webhooks/guides/getting-started) de la documentation de l'API.

## Qui peut ouvrir Webhooks

| Geste | Rôle minimum | Plan |
| ----- | ------------ | ---- |
| Ouvrir l'onglet **Webhooks** et voir la liste | Admin | Tous les plans |
| Créer, modifier, dupliquer ou supprimer un webhook | Admin | Tous 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.

![Onglet Webhooks avec le lien Open Svix dashboard, les boutons Fast alert set up et Custom alert, et trois webhooks dont un Disabled](https://docs.safecube.ai/media/images/shared/api-webhooks--list.webp?v=70172173)

## Liste des webhooks

| Colonne | Ce qu'elle affiche |
| ------- | ------------------ |
| **Webhook URL** | L'URL qui reçoit les events. Sélectionnez-la pour la copier. |
| **Events** | Le nombre d'events que le webhook envoie. |
| **Shipments** | Le nombre d'expéditions que le webhook suit. |
| **Status** | **Active**, ou **Disabled** quand le webhook n'envoie rien. |
| **Last update** | La 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.

![Onglet Webhooks avec une liste vide indiquant No webhooks](https://docs.safecube.ai/media/images/shared/api-webhooks--empty.webp?v=25c4a791)

## 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**.

![Étape Configuration de Custom alert avec l'URL de l'endpoint et les champs d'Optional information ouverts](https://docs.safecube.ai/media/images/shared/api-webhook-create--configuration.webp?v=ca686330)

![Étape Add shipments avec deux expéditions et l'expédition de démo dans le tableau Tracked shipments](https://docs.safecube.ai/media/images/shared/api-webhook-create--shipments.webp?v=0e3e9bb3)

![Étape Events avec la liste Search events ouverte sur le groupe Port of discharge, qui recouvre la plupart des events suivis](https://docs.safecube.ai/media/images/shared/api-webhook-create--events.webp?v=6755e35b)

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

| Champ | Ce qu'il règle |
| ----- | -------------- |
| **Disabled** | **True** arrête toute livraison vers l'URL, et la liste affiche **Disabled**. **False** garde le webhook actif. |
| **Rate limit**, **UID**, **Version**, **Description** | Options de l'endpoint, décrites dans la [référence de création d'un endpoint](/fr/api/webhooks/reference/endpoints/endpoint-create). |
| **Metadata** | Des 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](/fr/api/webhooks/guides/events).

## 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](/fr/api/webhooks/guides/getting-started).

![Page de détail d'un webhook avec la Webhook URL, l'ID et le Secret, les events suivis et les expéditions suivies](https://docs.safecube.ai/media/images/shared/api-webhook-details--default.webp?v=e2dd2018)

## 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](/fr/api/webhooks/guides/testing-your-endpoint).

## 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](/fr/api/webhooks/guides/failure-recovery).
- L'onglet n'affiche aucun payload : les données envoyées par chaque event sont décrites dans [Events de webhook](/fr/api/webhooks/guides/events).
- **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](/fr/platform/developers/api-credentials).
