Getting started with webhooks
Safecube webhooks, also called container tracking alerts, send tracking events to a public URL of your own as soon as Safecube detects them, instead of you polling the Container Tracking API. A webhook setup has two parts: an endpoint, which is the URL that receives the events together with the list of events it subscribes to, and the shipments monitored for that endpoint. Webhooks can be set up two ways: from the Safecube web application, or through the Webhooks API.
Set up webhooks from the Safecube web application
The webhook settings live in the Safecube web application at https://app.safecube.ai/api/webhooks: open Developers in the sidebar, then the Webhooks tab. Only an Admin or an Owner of the workspace can open it. The page offers two ways to create a webhook. Every screen of the tab is described in Webhooks console.
Option 1: Fast alert set up
Fast alert set up creates a webhook from its URL only:
- the webhook subscribes to the four default events
shipment.added.to.endpoint,shipment.any.change,shipment.auto.removedandshipment.in.error; - it follows no shipment, or the demo shipment
ZZZZ0000000only: the shipments your account already tracks are not added.
The tracked events and shipments can be edited afterwards; the events are chosen among those listed on the Webhook events page.
Option 2: Custom alert
Custom alert gives access to every webhook setting:
- advanced settings such as the description, metadata and rate limit of the endpoint;
- the specific shipments to monitor;
- the specific events to subscribe to.
Set up webhooks with the API
The Webhooks API is served at https://api.sinay.ai/webhook/api/v1. Every request is authenticated with your Safecube API key in the API_KEY header, as described on the Authentication page.
Create an endpoint
An endpoint is defined by three main parameters:
- The public URL where you want to receive the events. To test webhooks before your own URL is ready, use a Svix Playground URL.
- A secret that lets you check that the events come from Safecube. Leave it empty and Safecube generates it — setting your own secret is possible but not recommended.
- The events you want to receive, listed on the Webhook events page. The recommended events are
shipment.added.to.endpoint,shipment.in.error,shipment.any.changeandshipment.auto.removed.
Only the URL is required to create an endpoint; the other parameters can be edited later. Create the endpoint with 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"]
}'
The API answers 201 Created, and the response contains the endpoint ID (ep_…). Keep it: adding shipments requires it. To retrieve it later, list your endpoints with GET /endpoint.
Add shipments to monitor
Once the endpoint exists, add the shipments to monitor with POST /easy-shipment-asynchronous. The request body is keyed by endpoint ID, and each shipment needs:
- a shipment number: a container number, or a booking or bill of lading number;
- the shipping line (
sealine, SCAC code): optional for a container number, required with a booking or bill of lading number.
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" }]
}
}'
Each shipment then triggers a shipment.added.to.endpoint or a shipment.in.error event. The Adding shipments page explains how to react to each one.
To test webhooks with a demo shipment, add the container ZZZZ0000000 with no shipping line: it sends every event your endpoint subscribes to every 6 hours.
Integrate your webhooks
Send a sample webhook
POST /endpoint/{endpoint_id}/send-example sends a sample event to your endpoint at any time. Set the event type in the request body:
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" }'
The Testing your endpoint page lists every way to send test events.
Watch your webhooks in Svix Playground
When the endpoint URL is a Svix Playground URL, such as https://play.svix.com/in/{your_url_id}, the webhooks sent to it are visible in any browser at https://play.svix.com/view/{your_url_id}.
Verify the webhook signature
Every webhook sent to your endpoint is signed with a key unique to that endpoint. Get the endpoint secret with GET /endpoint/{endpoint_id}/secret: the response contains a base64-encoded key that verifies the payloads Safecube sends to the endpoint.
curl "https://api.sinay.ai/webhook/api/v1/endpoint/{endpoint_id}/secret" \
-H "API_KEY: $SAFECUBE_API_KEY" \
-H "Accept: application/json"
Safecube sends webhooks through Svix: the Svix verification guide details how to verify a payload with that key.
Monitor your webhooks
All the monitoring information on endpoints, messages and events is available through the Webhooks API endpoints, such as GET /endpoint/{endpoint_id}/stats. The Failure recovery page shows how to detect and resend failed webhooks.
The same information is also shown in a monitoring dashboard. GET /dashboard returns your own link to it:
curl "https://api.sinay.ai/webhook/api/v1/dashboard" \
-H "API_KEY: $SAFECUBE_API_KEY" \
-H "Accept: application/json"