# Webhooks console

> The Webhooks tab of the Developers page lets Admins and Owners create, review, edit, disable and delete the webhooks that push shipment events from Safecube to their own URL, in one click or step by step.

The **Webhooks** tab of the **Developers** page sets up webhooks: each webhook sends the events you choose, for the shipments you choose, to a URL of your own as soon as Safecube detects them. The tab lists your webhooks, creates them in one click or step by step, and shows, edits or deletes each one. The format of the events and how to receive them are described in the [Getting started with webhooks](/en/api/webhooks/guides/getting-started) guide of the API documentation.

## Who can open Webhooks

| Gesture | Minimum role | Plan |
| ------- | ------------ | ---- |
| Open the **Webhooks** tab and see the list | Admin | Every plan |
| Create, edit, duplicate or delete a webhook | Admin | Every plan |

An Editor or a Viewer does not see **Developers** in the sidebar, and a link to `/api/webhooks` takes them to the access denied page.

## Open the Webhooks tab

1. Select **Developers** in the sidebar.
2. Select the **Webhooks** tab.

The address `https://app.safecube.ai/api/webhooks` opens the tab directly. The top of the tab reads "Setup your webhook environment to receive real-time updates on your shipments." and holds:

- **Use our playground**, a link to the Svix playground, a free page that gives you a test URL to receive webhooks before your own URL is ready;
- **Open Svix dashboard**, a link to the Svix portal of your workspace, shown only once the portal exists;
- **Fast alert set up** and **Custom alert**, the two ways to create a webhook.

![Webhooks tab with the Open Svix dashboard link, the Fast alert set up and Custom alert buttons, and three webhooks, one of them Disabled](https://docs.safecube.ai/media/images/shared/api-webhooks--list.webp?v=70172173)

## Webhook list

| Column | What it shows |
| ------ | ------------- |
| **Webhook URL** | The URL that receives the events. Select it to copy it. |
| **Events** | The number of events the webhook sends. |
| **Shipments** | The number of shipments the webhook follows. |
| **Status** | **Active**, or **Disabled** when the webhook sends nothing. |
| **Last update** | The date of the last change to the webhook. |

Select a column header to sort the list on it. The list shows 10 webhooks per page, with a paginator beyond that. On each row, the eye button, **Webhook details**, opens the webhook, and the **…** menu holds **Duplicate config** and **Delete**.

Before your first webhook, the list reads **No webhooks**. When the list cannot be loaded, the toast "Failed to load webhook endpoints. Please try again later." appears.

![Webhooks tab with an empty list reading No webhooks](https://docs.safecube.ai/media/images/shared/api-webhooks--empty.webp?v=25c4a791)

## Set up a webhook in one click

1. Select **Fast alert set up**. The **One click webhook setup** dialog opens.
2. In **Enter endpoint URL**, type your URL after `https://`. The URL must start with `https://`.
3. Tick **Add demo shipment to my webhook** to receive test events from the demo shipment `ZZZZ0000000`.
4. Select **Create my webhook**.

The webhook sends the 4 default events, `shipment.added.to.endpoint`, `shipment.any.change`, `shipment.auto.removed` and `shipment.in.error`. It follows no shipment, or the demo shipment only: none of the shipments already tracked in your workspace is added. Add your shipments afterwards with **Edit webhook**.

On success, the dialog closes, the toast "Webhook endpoint created successfully." appears and the webhook tops the list. On failure, the dialog reads **Webhook creation failed**, with **Contact us** and **Try again**.

## Create a custom alert

**Custom alert** opens a page in three steps: **Configuration**, **Add shipments** and **Events**. Move between them with **Previous** and **Next**, or select a step at the top of the page. **Back** returns to the list.

1. **Configuration**: type the URL in **Enter endpoint URL**; it must start with `https://`. Turn on **Optional information** to set the options listed in the next section. **Next** stays disabled while the URL or the metadata is invalid.
2. **Add shipments**: type the **Shipment number**, keep **Auto Detect** or pick the carrier in **Type or select carrier**, choose the **Shipment type**, `CT` (container), `BL` (bill of lading) or `BK` (booking), then select **+**. Each shipment joins the **Tracked shipments** table. Tick **Add a demo shipment to test your webhook setup** to add the demo shipment.
3. **Events**: pick events in **Search events**. The 4 default events are already selected; each selected event appears under **Tracked events**, with a cross to remove it.
4. Select **Submit**.

![Configuration step of Custom alert with the endpoint URL and the Optional information fields open](https://docs.safecube.ai/media/images/shared/api-webhook-create--configuration.webp?v=ca686330)

![Add shipments step with two shipments and the demo shipment in the Tracked shipments table](https://docs.safecube.ai/media/images/shared/api-webhook-create--shipments.webp?v=0e3e9bb3)

![Events step with the Search events list open on the Port of discharge group, covering most of the tracked events](https://docs.safecube.ai/media/images/shared/api-webhook-create--events.webp?v=6755e35b)

With no shipment, **Warning!** reads "You are about to create a webhook with no tracked shipment you will not receive any alerts with these settings. Do you confirm creation ?". Select **Create webhook** to go on, or **Cancel**.

On success, the page reads **Your webhook is ready !** and warns that the tracked shipments may take a few minutes to be processed; **View all webhooks** returns to the list. On failure, it reads **Webhook Creation failed**, with **Contact us** and **Update selection**, which returns to the first step.

## Optional information

| Field | What it sets |
| ----- | ------------ |
| **Disabled** | **True** stops every delivery to the URL, and the list shows **Disabled**. **False** keeps the webhook active. |
| **Rate limit**, **UID**, **Version**, **Description** | Options of the endpoint, described in the [endpoint creation reference](/en/api/webhooks/reference/endpoints/endpoint-create). |
| **Metadata** | Data of your own attached to the webhook, in JSON. Otherwise the page reads "Metadata must be in JSON format". |

## Choose the events

**Search events** groups the events under **Port of discharge**, **Port of loading**, **Post POD**, **Pre POL**, **Shipment** and **Transshipment**. Each event shows its technical name, such as `shipment.any.change`; hover it to read what it means. The meaning of every event and the data it sends are described in the [Webhook events](/en/api/webhooks/guides/events) guide.

## View a webhook

Select the eye button of a row. The details page shows:

- **Configuration**: the **Webhook URL**, the **ID** of the webhook and its **Secret**, each with a copy button, and the **Optional information**;
- **Tracked events**;
- **Tracked shipments**, with **Shipment number**, **Sealine** and **Shipment type**.

The **Secret** is shown in clear: your server uses it to check that a webhook comes from Safecube, as described in [Getting started with webhooks](/en/api/webhooks/guides/getting-started).

![Webhook details page with the Webhook URL, ID and Secret, the tracked events and the tracked shipments](https://docs.safecube.ai/media/images/shared/api-webhook-details--default.webp?v=e2dd2018)

## Edit a webhook

1. Open the webhook and select **Edit webhook**.
2. Change the URL or the optional information, add or remove events under **Tracked events**, and add or remove shipments under **Tracked shipments**.
3. Select **Save**.

The page leaves edit mode at once, then the toasts "Webhook endpoint updated successfully." and "Webhook shipment updated successfully." confirm the change. A failure shows "Failed to update webhook endpoint. Please try again later." or "Failed to update webhook shipment. Please try again later.". The page has no **Cancel** button; **Back** leaves it.

To stop a webhook without deleting it, set **Disabled** to **True** under **Optional information**, then select **Save**.

## Duplicate a webhook

1. Open the **…** menu of a row and select **Duplicate config**.
2. **Custom alert** opens with the optional information, events and shipments of the webhook, but no URL and no UID.
3. Type the new URL, then go through the steps and select **Submit**.

## Delete a webhook

1. Open the **…** menu of a row and select **Delete**.
2. The **Delete webhook** dialog shows the URL and reads "This action cannot be undone. All associated data will be permanently deleted.".
3. Select **Delete**.

The toast "Webhook endpoint deleted successfully." appears and the row leaves the list. On failure, the dialog shows **Server error** with **Retry**. A webhook cannot be deleted from its details page.

## Test a webhook

- Use a Svix playground URL, from **Use our playground**, as the webhook URL to see the events in your browser.
- Add the demo shipment `ZZZZ0000000` to the webhook, when you create it or with **Edit webhook**, to receive test events.

Other ways to send test events are described in [Testing your webhook endpoint](/en/api/webhooks/guides/testing-your-endpoint).

## Limits

- The tab shows no delivery log, does not resend a failed event and does not rotate the secret: these are done in the Svix portal, from **Open Svix dashboard**, or through the API, as described in [Failure recovery](/en/api/webhooks/guides/failure-recovery).
- The tab shows no payload: the data each event sends is described in [Webhook events](/en/api/webhooks/guides/events).
- **Fast alert set up** adds none of your tracked shipments to the webhook.
- A webhook ID that does not exist opens an empty details page, with no error message.
- Rotating the API key of the workspace does not stop the existing webhooks: they keep delivering, as described in [API credentials](/en/platform/developers/api-credentials).
