Webhooks

Last updated 5 months ago

Webhooks allow you to subscribe to events that Shippify generates every time a delivery or route is changed. When one of those events is triggered, we'll send a HTTP POST request to the webhook's configured URL.

Webhook Setup

Declaring a Webhook

In your Shippify account, go to the setting section and look for `Webhooks` in the left side menu.

In this section you can manage the URL's you declare for each of the events you want to subscribe to. You can also test your webhooks in this section and you'l receive a sample payload.

You can also subscribe URLs in a programatic way here :

Available Webhook Events

Specification of event codes available for webhooks:

Status

Name

Description

1

Create delivery

Fires whenever a new delivery is created.

2

Create route

Files whenever a new route is created.

3

Update delivery

Fires whenever a delivery is updated.

New delivery

When creating a new delivery, the webhook is executed and sends the following payload:

Payload received in URL:

{
"id" // Task id. (string)
"route_id" // Route id. (string)
"distance" // Total route distance in kilometers. (double)
"date" // Route creation date. (string) (unix_timestamp)
"price" // Task discounted price. (string)
"currencySign" // $
}

New route

Payload received in URL:

{
"id" // Task id. (string)
"route_id" // Route id. (string)
"distance" // Total route distance in kilometers. (double)
"date" // Route creation date. (string) (unix_timestamp)
"price" // Task discounted price. (string)
"currencySign" // $
}

Update delivery

Payload received in URL:

{
"id" // Task id. (string)
"route" // Route id. (string)
"orderId" // the id on your system (string)
"status" // Task current status. (int)
"_status" // Task current micro status. (string)
"company_id" // Company id assigned to task. (string)
"city_id" // City id assigned to task. (string)
"timestamp" // when the event happened (milliseconds)
}

Webhook Management

Subscribing an URL to a webhook

Endpoint POST /hooks/companies/:company_id

  • Creates a webhook by subscribing an url to an specific event from the Shippify engine.

Schema

Request

{
"url" // Subscription URL string. (string),
"action" // Subscription event id from Shippify. See table below. (integer)
}

Example

curl
-X POST
-H 'Accept-Charset: utf-8'
-u '**APIKeyId**:**APISecretId*'
-d 'url=https://my_website_url.com'
-d 'action=2'
"https://api.shippify.co/hooks/companies/34"

Fetching all subscribed URLs

Endpoint GET /hooks/companies/:company_id

  • Fetches all urls subscribed through webhooks to a company's events.

Schema

Response

[
{ // Hook object
"url" // Subscription URL string. (string),
"action" // Subscription event id from Shippify. See table below. (integer)
"status" // Subscription URL status, active or blacklisted. (string)
}
]

Example

curl
-X GET
-u '**APIKeyId**:**APISecretId*'
"https://api.shippify.co/hooks/companies/54"

Payload

[
{
"action": 2,
"url": "https://my_website_webhook.com/url",
"status": "Active"
},
{
"action": 3,
"url": "https://my_faulty_website_webhook.com/url",
"status": "Banned"
}
]

Unsubscribing an URL to a webhook

Endpoint DELETE /hooks/companies/:company_id

  • Destroys a webhook by unsubscribing an url from an specific event from the Shippify engine.

Schema

Request

{
"url" // Subscription URL string. (string),
"action" // Subscription event id from Shippify. See table below. (integer)
}

Example

curl
-X DELETE
-H 'Accept-Charset: utf-8'
-u '**APIKeyId**:**APISecretId*'
-d 'url=https://my_website_url.com'
-d 'action=3'
"https://api.shippify.co/hooks/companies/34"