🚀Getting Started with Webhooks
Creating and setting up a webhook in Sinay’s webhook API can be done in 2 ways.
From the Webhook dashboard
Welcome to the new Webhooks Management Interface : a dedicated space to create and manage webhooks (container tracking alerts) directly from the dashboard for a quick & easy experience.
Go to My Account > Container Tracking Alerts
Option 1 : Fast Alert Set up
Select Fast Alert Set Up to create an alert based on your account's historical data
- This will automatically enroll all the shipments you are currently tracking
- Webhooks will be created on 2 default events : container discharged at POD and container discharged at POD date changed (over 24h)
You can edit tracked events and choose any among the following.
Option 2 : Custom Alert Set Up
Select Custom Alert Set Up to customize all webhooks settings
- Use advanced settings to define specific parameters (description, metadata, rate limit...)
- Add specific shipments
- Add specific events
Webhooks (Container tracking Alerts) are a paid feature, subscribe to our pay-you-go plan to get started.
Via API
Create an application
Use the endpoint POST /application
to create your application. Just give it a name, it will be used to identify your webhooks.
This is done by using the endpoint POST /application
and specifying your application name. Your enterprise name is a good choice.
curl -X 'POST' \
'https://api.sinay.ai/application' \
-H 'accept: application/json' \
-H 'API_KEY: ' \
-H 'Content-Type: application/json' \
-d '{
"name": "My first application"}'
You should specify only your application name. The expected response code is 201 “Resource Created”
Create an endpoint in this app
Once you have created your application, you can create endpoints. An endpoint is an object with at least 3 parameters :
- The public URL where you would like to receive the events
For test purposes, you can use Svix Playground to test our webhooks https://www.svix.com/play/ - A secret that will allow you to make sure the events are coming from Sinay. The secret will be auto generated by us (you can specify it if you wish, but it’s not recommended).
- The events you wish to receive. List of possible events
To create an endpoint, you can just specify the public URL. The other parameters can be edited later.
Use the endpoint POST /endpoint
to create a new endpoint : the expected answer is a 201 “Resource created”. The answer will contain your endpoint id. Note it, it will be used in the next step. If you forget, retrieve it with GET /endpoint.
curl -X 'POST' \
'https://api.sinay.ai/webhook/api/v1/endpoint' \
-H 'idempotency-key: fb8a1e67-59ad-4ae6-a42a-a8f8f159f4a4' \
-H 'accept: application/json' \
-H 'API_KEY: ' \
-H 'Content-Type: application/json' \
-d '{
"description": "An example endpoint name",
"url": "https://example.com/webhook/",
"filterTypes": [
"container.discharge_final_pod"
]
}'
Add shipments to be monitored
Now, you have created you application and added an endpoint. You just need to specify which containers you wish to follow. You can do this via the POST /easy-shipment
endpoint.
You will need to specify :
- The endpoint id you wish to use to track those containers
If you haven't noted it, you can retrieve that ID with the request GET /endpoints
- The container number (and associated sealine if you have it) or the booking/Bill of Lading reference with the associated sealine.
If you wish to test our Webhooks with a demo shipment, specify the container "ZZZZ0000000" with no sealine. If you do so, you will be sent every webhook you subscribe to every 6 hour.
curl --location 'https://api.sinay.ai/webhook/api/v1/easy-shipment' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'API_KEY: ••••••' \
--data '{
"ep_2hMa1FHBpIQGkZ0QOOvYire4WJu": {
"shipments": [
{
"number": "TIIU4429132"
}
]
}
}'
Integrate your webhooks
You can now use the webhooks you have set up. To do so, note that you can send a sample event to your endpoint. You can then verify that webhook content either using our playground or by verifying it in your code.
Send a sample webhook
By sending a POST request to /endpoint/{endpoint_id}/send-example
you will be able to send a sample webhook at any time to test your endpoint.
Just specify the event type you wish to receive a sample for in the request body.
curl --location 'https://api.sinay.ai/webhook/api/v1/endpoint/{endpoint_id}/send-example' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'API_KEY: ' \
--data '{
"eventType": "vessel.departure.from.transhipment_port"
}'
Watch your webhooks using Playground
If you set up your webhook endpoint by using a playground url, such as "https://play.svix.com/in/{your_url_id}", then you will be able to simply see the webhooks that are sent to your endpoint using the url "https://play.svix.com/view/{your_url_id}" in any browser.
This is what the interface will look like.
Verify your webhook signature
Webhooks sent to your endpoint will be signed with a key which is unique to your endpoint. You can use the endpoint secret to verify the webhooks you will receive. Find the complete verification guide at https://docs.svix.com/receiving/verifying-payloads/why
To get your endpoint secret, use the endpoint GET /endpoint/{endpoint_id}/secret
The response will contain a base64 encoded key that you can use to verify the payload tha Sinay will send to your endpoints.
curl --location 'https://api.sinay.ai/webhook/api/v1/endpoint/ep_2ZD62qcgs04kKGLSNdA7V0MBI0e/secret' \
--header 'Accept: application/json' \
--header 'API_KEY: ' \
Monitor your webhooks
To ease up the monitoring of your webhook, you can use the endpoints provided, or use a dashboard.
To retrieve your dashboard url, use the endpoint GET /dashboard
.
curl -X 'GET' \
'https://api.sinay.ai/webhook/api/v1/dashboard' \
-H 'accept: application/json' \
-H 'API_KEY: '
In the response, you will find your own link to your dashboard.
In your dashboard, you will have access to a lot of monitoring information regarding the endpoints, logs and events. Note that all information available in the dashboard can also be retrieved using Sinay’s Webhook API endpoints.
Updated 8 days ago
Create your first webhook using our dashboard, or deep dive into implementation best practices