Delivery webhook events

Please refer to Business orders Delivery Webhook documentation in order to find out how to subscribe or unsubscribe to webhooks
You can subscribe with more than one webhook address

Note:
Our webhook service has the ability to resending webhook events in case the webhook address is not reachable due to 5xx server error.
In order to activate it, "retries":N" must be added right after the "hook_address".
'N' is the retry interval.
The retry intervals will grow exponentially from 1 minute to 30 minutes and will be made up to N times.
Once the event reaches the address successfully, the webhook service will stop resending

Event "delivery_status_changed"

For all order changes, Gett's server will make a POST request to the hook_address used in the Subscribe Webhook step with message containing a json string with the following format:

Parameter name

Type

Description

product_id

string

The unique ID of the specific product.

delivery_id

string

Unique id for the delivery request

status

string

One of delivery Lifecycle status

courier

object

Conditional - on status "confirmed"

courier.name

string

Courier who will pick up the package

courier.phone

string

Phone number of the courier

cannot_deliver_info

object

Conditional - on status "cancelled" or "not_delivered"

cannot_deliver_info.description

string

A localized string based on reason id or free text provided by the courier

cannot_deliver_info.reason_id

integer

One of pre-defined reasons for company

cannot_deliver_info.reason_type

string

One of pre-defined reasons for company

env

string

Information about environment source.
If the event is from sandbox:
"Env":"sandbox"
If the event is from production:
"Env":"prod"

rejection_info

string

Information about the reason of rejection

verifications

object

Proof about who got the package(s)

proof

object

Object that hold the data

code_provided

boolean

sms verification code a recipient received to provide to the currier in order complete the delivery
possible values:
true/false

recipient_category

string

Three type of recipient_category can be set:

"default" - when the origin recipient got the package

"other" - when someone else got the package

"unattended" - when the package left in safe place

recipient_name

string

Who got the package

signature_provided

boolean

Information if the recipient has signed

Possible values:
true/false

verified_by

string

Which courier has delivered

proved_at

timestamp

The time courier has delivered the package
Date Format

display_identifier

string

A string label that identify the delivery. e.g. "package001"

external_identifier

string

Any identifier to help you map deliveries created with your entities .

{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "delivery_status_changed",
  "message": 
  "{\"courier\":  {\"name\": \"John Doe\",
    \"phone\": \"051-1234567\"},    
    \"display_identifier\":\"15410220\",    
    \"delivery_id\": \"DR-0751c44f627347c3b2fcc56223299b05\",    
    \"env\": \"prod\",
    \"external_identifier\":\"delivery external identifier\"    
    \"product_id\":  \"22d4b9ef-e9bc-47e3-b70f-ff2b06e1a869\",    
    \"status\": \"confirmed\" }"
}
{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "delivery_status_changed",
  "message": 
  "{\"delivery_id\": \"DR-437e9eeb2d0f444199643bbeefab6dea\",
  \"display_identifier\": \"15410220\",
  \"env\": \"prod\",
\"external_identifier\":\"delivery external identifier\"
  \"product_id\": \"22d4b9ef-e9bc-47e3-b70f-ff2b06e1a869\",
  \"status\": \"waiting\"}"
}
{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "delivery_status_changed",
  "message": 
  "{\"delivery_id\": \"DR-f598a4f5d68a4c09a9d16719d84c3822\",
  \"display_identifier\": \"15410220\",
  \"env\": \"prod\",
\"external_identifier\":\"delivery external identifier\"
  \"product_id\": \"22d4b9ef-e9bc-47e3-b70f-ff2b06e1a869\",
  \"status\": \"picked_up\"}"
}
{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "delivery_status_changed",
  "message": 
  "{\"delivery_id\": \"DR-f598a4f5d68a4c09a9d16719d84c3822\",
  \"display_identifier\": \"15410220\",
  \"env\": \"prod\",
\"external_identifier\":\"delivery external identifier\" 
  \"product_id\": \"22d4b9ef-e9bc-47e3-b70f-ff2b06e1a869\",
  \"status\": \"driving\"}"
}
{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "delivery_status_changed",
  "message": 
  "{\"delivery_id\": \"DR-f598a4f5d68a4c09a9d16719d84c3822\",
  \"display_identifier\": \"15410220\",
  \"env\": \"prod\",
\"external_identifier\":\"delivery external identifier\" 
  \"product_id\": \"22d4b9ef-e9bc-47e3-b70f-ff2b06e1a869\",
  \"status\": \"at_drop_off\"}"
}
{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "delivery_status_changed",
  "message": 
  "{
   \"delivery_id\": \"DR-f549218c09584ac4b40d36f29321652e\",
  \"display_identifier\": \"15410220\",
  \"env\": \"prod\",
\"external_identifier\":\"delivery external identifier\" 
  \"product_id\": \"65655a5d-35df-4648-9661-615b341a7b79\",
  \"status\": \"completed\",
  \"verifications\": [
    null,
    {
      \"proof\": {
        \"code_provided\": false,
        \"recipient_category\": \"default\",
        \"recipient_name\": \"John\",
        \"signature_provided\": false,
        \"verified_by\": \"1211\"
      },
      \"proved_at\": \"2020-10-20T06:56:12.979468Z\",
      \"type\": \"recipient\"
    }
  ]
}"
}
{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "delivery_status_changed",
  "message": 
  "{\"cannot_deliver_info\": {
    \"cancelled_by\": \"supplier\",
    \"description\": \"client_refused\",
    \"reason_id\": 14,
    \"reason_type\": \"client refused\"
  },
  \"delivery_id\": \"DR-cdebab9c72ff4842a88acda5aa9f8073\",
  \"display_identifier\": \"15410220\", 
  \"env\": \"prod\",
\"external_identifier\":\"delivery external identifier\" 
  \"product_id\": \"22d4b9ef-e9bc-47e3-b70f-ff2b06e1a869\",
  \"status\": \"not_delivered\"
}"
}
{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "delivery_status_changed",
  "message": 
  "{\"cannot_deliver_info\": {
    \"cancelled_by\": \"cc\",
    \"description\": \"Missing\",
    \"reason_type\": \"\"
  },
  \"delivery_id\": \"DR-51e24415b7cd43ee9f4b141f91923055\",
  \"display_identifier\": \"15410220\",  
  \"env\": \"prod\",
\"external_identifier\":\"delivery external identifier\" 
  \"product_id\": \"22d4b9ef-e9bc-47e3-b70f-ff2b06e1a869\",
  \"status\": \"cancelled\"
}"
}
{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "delivery_status_changed",
  "message": 
  "{\"delivery_id\": \"DR-4e1d7cb33c3d46cbb46e63f2fd66a163\",
  \"env\": \"prod\",
\"external_identifier\":\"delivery external identifier\"
  \"display_identifier\": \"15410220\",
  \"product_id\": \"22d4b9ef-e9bc-47e3-b70f-ff2b06e1a869\",
  \"rejection_info\": {
    \"description\": \"drop_off: Drop off not allowed because it is out of the defined service area for the selected pickup point\"
  },
  \"status\": \"rejected\"
}"
}

Event "delivery_parcel_status_changed"

One delivery can include several parcels.
The parcel statuses can be one of the following:
initial, completed, cancelled, not_delivered
In this case, the message will include:

Parameter name

Type

Description

delivery_id

String

Unique id for the delivery request

env

String

Information about environment source.
If the event is from sandbox:
"Env":"sandbox"
If the event is from production:
"Env":"prod"

parcel_id

String

Unique id for the parcel request

status

String

The relevant status for the parcel

cannot_deliver_info

Object

This object contains the cannot delivered info

cancelled_by

String

Who cancelled the parcel, by CC (customer care) or by driver

description

String

Textual reason

display_identifier

String

A string label that identify the delivery. e.g. "package001"

external_identifier

string

Any identifier to help you map deliveries created with your entities .

{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "delivery_parcel_status_changed",
  "message": 
  "{\"delivery_id\": \"DR-f598a4f5d68a4c09a9d16719d84c3822\",
  \"display_identifier\": \"15410220\",
  \"env\": \"prod\",
  \"external_identifier\":\"parcel external iden\",
  \"parcel_id\": \"P-b12abe76feb9436db65c401d6317af03\",
  \"status\": \"initial\"
}"
}
{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "delivery_parcel_status_changed",
  "message": 
  "{\"cannot_deliver_info\": {
    \"cancelled_by\": null
  },
  \"delivery_id\": \"DR-cdebab9c72ff4842a88acda5aa9f8073\",
  \"display_identifier\": \"15410220\",
  \"env\": \"prod\",
  \"external_identifier\":\"parcel external iden\",
  \"parcel_id\": \"P-ba207c3f3b024c77b907402653270589\",
  \"status\": \"not_delivered\"}"
}
{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "delivery_parcel_status_changed",
  "message": 
  "{\"cannot_deliver_info\": {
    \"cancelled_by\": \"cc\",
    \"description\": \"Missing in warehouse\"
  },
  \"delivery_id\": \"DR-51e24415b7cd43ee9f4b141f91923055\",
  \"display_identifier\": \"15410220\",
  \"env\": \"prod\",
  \"external_identifier\":\"parcel external iden\",
  \"parcel_id\": \"P-ff8abc4e6a134efea5657967e4055f99\",
  \"status\": \"cancelled\"}"
}
{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "delivery_parcel_status_changed",
  "message": 
  "{\"delivery_id\": \"DR-f598a4f5d68a4c09a9d16719d84c3822\",
  \"display_identifier\": \"15410220\",
  \"env\": \"prod\",
  \"external_identifier\":\"parcel external iden\",
  \"parcel_id\": \"P-b12abe76feb9436db65c401d6317af03\",
  \"status\": \"picked_up\"
}"
}
{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "delivery_parcel_status_changed",
  "message": 
  "{\"delivery_id\": \"DR-f598a4f5d68a4c09a9d16719d84c3822\",
  \"display_identifier\": \"15410220\",
  \"env\": \"prod\",
  \"external_identifier\":\"parcel external iden\",
  \"parcel_id\": \"P-b12abe76feb9436db65c401d6317af03\",
  \"status\": \"completed\"}
"}

Event "delivery_courier_unassigned"

This event will be triggered for each delivery once the currier was unassigned from picking up the package.

Parameter name

Type

Description

delivery_id

String

Unique id for the delivery request

display_identifier

String

A string label that identify the delivery. e.g. "package001"

env

String

String Information about environment source.
If the event is from sandbox:
"Env":"sandbox"
If the event is from production:
"Env":"prod"

{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "delivery_courier_unassigned",
  "message": 
  "{\"delivery_id\":\"DR-0570de0cb1834b5d9bae45cae2f48777\",
    \"display_identifier\":\"M87483H8F889\",\"env\":\"prod\"
    \"external_identifier\":\"delivery external identifier\"}"
}

Event "routes_optimization_ended"

If a bundle of deliveries is set to be optimized, a webhook event "routes_optimization_ended" will be triggered when the optimization completes. The optimization process may take several minutes, according to the size of the bundle.

Parameter name

Type

Description

bundle_id

string

bundle id received when creating a bundle / deliveries. This

routes

object

An array of routes object. Each route contains a list of deliveries.

routes[i].display_identifier

string

An identifier for the route. e.g "Gett-01"
The value will be set by the Bundle's display identifier
In case the display identifier is empty, Gett will set default value: "gett-X"

routes.deliveries

delivery

An array of delivery requests

routes[i].deliveries[x].id

string

delivery id received when creating a delivery

routes[i].deliveries[x].display_identifier

string

A string label that identify the delivery. e.g. "package001"

env

string

Information about environment source.
If the event is from sandbox:
"Env":"sandbox"
If the event is from production:
"Env":"prod"

{
  "id": "537892e2-fbd0-4712-a1ea-a79cebeae372",
  "timestamp": "2018-03-18T12:00:25.543804071+02:00",
  "event_type": "routes_optimization_ended",
  "message": 
  "{
  \"bundle_id\": \"B-9704840ec1eb40da962697f30f651a05\",
  \"env\": \"prod\",
  \"routes\": [
    {
      \"deliveries\": [
        {
          \"display_identifier\": \"6207500\",
          \"id\": \"DR-89e02414371f4d6f9de13932eb507167\"
        },
        {
          \"display_identifier\": \"6207475\",
          \"id\": \"DR-904cd5d382f846319bf4160c6f8cc283\"
        },
        {
          \"display_identifier\": \"6207608\",
          \"id\": \"DR-ff312e2d27204765b8ff2dc7f3401429\"
        },
        {
          \"display_identifier\": \"6207477\",
          \"id\": \"DR-a4f047ad9a614f6690430c73e58ccf10\"
        }
      ],
      \"display_identifier\": \"gett-1\"
    },
    {
      \"deliveries\": [
        {
          \"display_identifier\": \"6207523\",
          \"id\": \"DR-279301c710b64f50b65a930032a216d6\"
        },
        {
          \"display_identifier\": \"6207323\",
          \"id\": \"DR-62f7febfac454028af67bd1e89630643\"
        }
      ],
      \"display_identifier\": \"gett-2
    },
    {
      \"deliveries\": [
        {
          \"display_identifier\": \"6207542\",
          \"id\": \"DR-d8fd07c63d78401fa860df472a197774\"
        },
        {
          \"display_identifier\": \"6207071\",
          \"id\": \"DR-60c4d96ca54a4559a418ad765865744a\"
        },
        {
          \"display_identifier\": \"6207602\",
          \"id\": \"DR-83cf50f1ee644714849ec58796787d06\"
        }
      ],
      \"display_identifier\": \"gett-3\"
    }
  ]
}"}

Sandbox

Webhook events can be sent also for Delivery Sandbox requests

If you subscribed (with scope = business) to notifications, you can test them in the following way:

First, Create a delivery using Create delivery Delivery](doc:delivery) but use the sandbox URL

In order to receive "delivery_status_changed" and "delivery_parcel_status_changed" events,
You should mock status update with a special status update request. A detailed explanation appears in Delivery Sandbox

In order to receive "routes_optimization_ended" event,
You should mock optimization ending with a special optimization_end request. A detailed explanation appears in Delivery Sandbox


Did this page help you?