# Getting started with webhooks

> Safecube webhooks push container tracking events to your own URL — set them up from the Developers > Webhooks page of the Safecube web application, or through the Webhooks API by creating an endpoint and adding shipments to it.

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](/en/platform/developers/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.removed` and `shipment.in.error`;
- it follows no shipment, or the demo shipment `ZZZZ0000000` only: 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](/en/api/webhooks/guides/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](/en/api/getting-started/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](https://www.svix.com/play/) 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](/en/api/webhooks/guides/events) page. The recommended events are `shipment.added.to.endpoint`, `shipment.in.error`, `shipment.any.change` and `shipment.auto.removed`.

Only the URL is required to create an endpoint; the other parameters can be edited later. Create the endpoint with [`POST /endpoint`](/en/api/webhooks/reference/endpoints/endpoint-create):

```bash
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`](/en/api/webhooks/reference/endpoints/endpoint-list).

### Add shipments to monitor

Once the endpoint exists, add the shipments to monitor with [`POST /easy-shipment-asynchronous`](/en/api/webhooks/reference/easy-shipment/easy-shipment-add-async). 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.

```bash
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](/en/api/webhooks/guides/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`](/en/api/webhooks/reference/endpoints/endpoint-send-example) sends a sample event to your endpoint at any time. Set the event type in the request body:

```bash
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](/en/api/webhooks/guides/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`](/en/api/webhooks/reference/endpoints/endpoint-get-secret): the response contains a base64-encoded key that verifies the payloads Safecube sends to the endpoint.

```bash
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](https://docs.svix.com/receiving/verifying-payloads/why) 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`](/en/api/webhooks/reference/endpoints/endpoint-get-stats). The [Failure recovery](/en/api/webhooks/guides/failure-recovery) page shows how to detect and resend failed webhooks.

The same information is also shown in a monitoring dashboard. [`GET /dashboard`](/en/api/webhooks/reference/application/application-dashboard) returns your own link to it:

```bash
curl "https://api.sinay.ai/webhook/api/v1/dashboard" \
  -H "API_KEY: $SAFECUBE_API_KEY" \
  -H "Accept: application/json"
```

::callout{type="warning"}
The dashboard link is unique. Requesting a new link with `GET /dashboard` expires every previous link.
::
