Webhooks console
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 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
- Select Developers in the sidebar.
- 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.
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.
Set up a webhook in one click
- Select Fast alert set up. The One click webhook setup dialog opens.
- In Enter endpoint URL, type your URL after
https://. The URL must start withhttps://. - Tick Add demo shipment to my webhook to receive test events from the demo shipment
ZZZZ0000000. - 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.
- 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. - 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) orBK(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. - 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.
- Select Submit.
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. |
| 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 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.
Edit a webhook
- Open the webhook and select Edit webhook.
- Change the URL or the optional information, add or remove events under Tracked events, and add or remove shipments under Tracked shipments.
- 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
- Open the … menu of a row and select Duplicate config.
- Custom alert opens with the optional information, events and shipments of the webhook, but no URL and no UID.
- Type the new URL, then go through the steps and select Submit.
Delete a webhook
- Open the … menu of a row and select Delete.
- The Delete webhook dialog shows the URL and reads "This action cannot be undone. All associated data will be permanently deleted.".
- 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
ZZZZ0000000to 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.
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.
- The tab shows no payload: the data each event sends is described in Webhook 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.