Subscribing to various types of events such as pickup or delivery
"Webhooks allow you to build or setup applications which subscribe to certain events on Yojee."
This mechanism is also useful for services that are not directly responsible for making an API request, but still need to know the response from that request.
When your application receives an update webhook call, it will most likely want to gather all information about the updated item, for which it can call the following track order detail API call.
In order to receive task update notifications, you can provide an endpoint for webhooks which we will call on any update of your order item(s).
When one of those events is triggered, we will send an HTTP POST payload to the webhook's configured URL. For the time being, please inform support@yojee.com with the URL that we should call.
Events
When configuring a webhook, you can choose which events you would like to receive payloads for. You can change the list of subscribed events through the API anytime.
Each event corresponds to a certain set of actions that can happen to your account. For example, if you subscribe to the order.created event you'll receive detailed payloads every time an order is created.
Order Created Payload Sample
{
"company_slug": "yojee",
"created_at": 1573616200,
"data": {
"cancelled_at": null,
"completion_time": null,
"container_no": null,
"display_price": null,
"external_id": null,
"id": 3465,
"inserted_at": "2019-11-13T03:36:19.446090Z",
"number": "O-IWWYG6ADYLLW",
"order_items": [
{
"external_customer_id": null,
"external_customer_id2": null,
"external_customer_id3": null,
"id": 14411,
"inserted_at": "2019-11-13T03:36:19.473411Z",
"item": {
"description": null,
"global_tracking_number": "Y-V6QYRPCGCU9B",
"height": "50",
"id": 14279,
"length": "50",
"payload_type": "package",
"quantity": null,
"volume": "125000",
"volumetric_weight": "25",
"weight": "30",
"width": "50"
},
"service_type": "next_day",
"status": "created",
"tracking_number": "YOJ-ZWRW1ZBWF5MZ",
"transfer_info": null
}
],
"price": null,
"sender": {
"id": 745,
"name": null,
"organisation_name": "Nikola Test Company",
"type": "organisation"
},
"status": "accepted"
},
"event_type": "order.created",
"id": "72574e3c-77e1-445f-805a-5c246d4dda55",
"webhook_id": 96,
"yojee_instance": "https://umbrella-dev.yojee.com"
}
Delivery Headers
HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain a header.
| Header | Description |
| yojee-signature | The HMAC hex digest of the response body. The HMAC hex digest is generated using the sha256 hash function and the secret as the HMAC key. |
Responding to a Webhook
To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. All response codes outside this range, including 3xx codes, will indicate to Yojee that you did not receive the webhook.
"We will attempt to deliver your webhooks for up to five times with an exponential back off."
| Retry | Seconds |
| 1 | 120 |
| 2 | 360 |
| 3 | 840 |
| 4 | 1800 |
| 5 | 3720 |
Best Practices
If your webhook script performs complex logic, or makes network calls, it's possible that the script would time out before Yojee sees its complete execution. For that reason, you might want to have your webhook endpoint immediately acknowledge receipt by returning a 2xx HTTP status code, and then perform the rest of its duties.
Checking Webhook Signatures
Yojee signs the webhook events it sends to your endpoints. We do so by including a signature using a hash-based message authentication code (HMAC) with SHA-256 in each event’s yojee-signature header. This allows you to validate that the events were sent by Yojee, not by a third party.
Before you can verify signatures, you need to retrieve your endpoint’s secret from us. Each secret is unique to the endpoint to which it corresponds.
Step 1: Get timestamp and signature from the header
Retrieve the yojee-request-timestamp and yojee-signature header on the HTTP request.
Step 2: Prepare the signed payload string
You achieve this by concatenating: * The timestamp (as a string) * The character . * The actual JSON payload (i.e., the request’s body)
Step 3: Determine the expected signature
Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed payload string as the message.
Step 4: Compare signatures
Compare the signature in the HEADER to the expected signature. If a signature matches, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.
Event Object
| Attributes | Description |
| id | Unique identifier for the event. |
| event_type | Description of the event (e.g. order.created or payment.completed). |
| data | Object containing data associated with the event. |
| webhook_id | The id of webhook which subscribes the event |
| created_at | Time at which the event was created. Measured in seconds since the Unix epoch. |
Please be informed that we are still in the process of integrating webhooks on all places where items can get updated and we will update this documentation as we add new webhooks.
More detailed information about the Webhooks API can be found at https://api-docs.yojee.com/#Yojee-APIs-[Dispatcher]-Webhook
List of Available Webhooks
|
S.No |
Event Name |
Description |
|
1 |
sender.created |
When a Sender is created within the backend. |
|
2 |
payment.completed |
When a payment is completed by the sender for an order (it's only fired for Individual Senders who prepay for their delivery order, e.g. credit card. Organisational Senders don't prepay most of the time, so it doesn’t get triggered). NOTE: Requires Stripe integration for testing purposes. |
|
3 |
order.created |
When an Order has been created in the backend. |
|
4 |
task.completed |
When a task (assigned to a driver - pickup / drop) is completed. |
|
5 |
task.accepted |
When a task (assigned to a driver - pickup / drop) is accepted. |
|
6 |
task.failed |
When a task (assigned to a driver - pickup / drop) is reported. |
|
7 |
task.reassigned |
When a task (assigned to a driver & not accepted yet) is reassigned. |
|
8 |
task.transferred |
When a task is transferred to an upstream / downstream partner. |
|
9 |
order_item.cancelled |
When an Order Item is cancelled. |
|
10 |
driver.arrived |
When a driver has arrived at the pickup / drop-off destination point. |
|
11 |
driver.departed |
When a driver has departed from the pickup / drop-off destination point. |
|
12 |
order.transfer.rejected |
When a transferred Order is rejected by the downstream partner. |
More Webhook Payload Samples
Order_Item.Cancelled
{
"company_slug": "yojee",
"created_at": 1573616529,
"data": {
"event_time": "2019-11-13T03:40:44.802915Z",
"external_customer_id": null,
"external_customer_id2": null,
"external_customer_id3": null,
"tracking_number": "YOJ-ZWRW1ZBWF5MZ"
},
"event_type": "order_item.cancelled",
"id": "1c0d2750-b75b-4831-b7d2-2c79a1ef36ce",
"webhook_id": 96,
"yojee_instance": "https://umbrella-dev.yojee.com"
}
Task.Accepted
PICKUP
{
"company_slug": "yojee",
"created_at": 1573618207,
"data": {
"driver": {
"id": 683,
"name": "Nikola Test Driver"
},
"event_time": "2019-11-13T04:08:36.848982Z",
"id": 35852,
"inserted_at": "2019-11-13T04:02:50.850823Z",
"order_item": {
"external_customer_id": null,
"external_customer_id2": null,
"external_customer_id3": null,
"tracking_number": "YOJ-VBBS9LFIOBG9"
},
"task_type": "pickup"
},
"event_type": "task.accepted",
"id": "4f8d2be4-1306-465e-8651-1e0d5b86c8e6",
"webhook_id": 96,
"yojee_instance": "https://umbrella-dev.yojee.com"
}
DROP-OFF
{
"company_slug": "yojee",
"created_at": 1573618207,
"data": {
"driver": {
"id": 683,
"name": "Nikola Test Driver"
},
"event_time": "2019-11-13T04:08:36.848982Z",
"id": 35851,
"inserted_at": "2019-11-13T04:02:50.850823Z",
"order_item": {
"external_customer_id": null,
"external_customer_id2": null,
"external_customer_id3": null,
"tracking_number": "YOJ-VBBS9LFIOBG9"
},
"task_type": "dropoff"
},
"event_type": "task.accepted",
"id": "16f40019-424e-4a29-baa2-a7886c661921",
"webhook_id": 96,
"yojee_instance": "https://umbrella-dev.yojee.com"
}
Driver.Arrived
{
"company_slug": "yojee",
"created_at": 1573618472,
"data": {
"driver": {
"id": 683,
"name": "Nikola Test Driver"
},
"event_time": "2019-11-13T04:12:47.529000Z",
"id": 35852,
"inserted_at": "2019-11-13T04:02:50.850823Z",
"order_item": {
"external_customer_id": null,
"external_customer_id2": null,
"external_customer_id3": null,
"tracking_number": "YOJ-VBBS9LFIOBG9"
},
"task_type": "pickup"
},
"event_type": "driver.arrived",
"id": "6e450fe1-973c-4056-b588-11b433095718",
"webhook_id": 96,
"yojee_instance": "https://umbrella-dev.yojee.com"
}
Driver.Departed
{
"company_slug": "yojee",
"created_at": 1573618776,
"data": {
"driver": {
"id": 683,
"name": "Nikola Test Driver"
},
"event_time": "2019-11-13T04:18:11.016000Z",
"id": 35852,
"inserted_at": "2019-11-13T04:02:50.850823Z",
"order_item": {
"external_customer_id": null,
"external_customer_id2": null,
"external_customer_id3": null,
"tracking_number": "YOJ-VBBS9LFIOBG9"
},
"task_type": "pickup"
},
"event_type": "driver.departed",
"id": "f17246f9-35ab-44c6-96c8-0061cb1dcf08",
"webhook_id": 96,
"yojee_instance": "https://umbrella-dev.yojee.com"
}
Task.Completed
{
"company_slug": "yojee",
"created_at": 1573619045,
"data": {
"driver": {
"id": 683,
"name": "Nikola Test Driver"
},
"event_time": "2019-11-13T04:22:18.000000Z",
"id": 35851,
"inserted_at": "2019-11-13T04:02:50.850823Z",
"order_item": {
"external_customer_id": null,
"external_customer_id2": null,
"external_customer_id3": null,
"tracking_number": "YOJ-VBBS9LFIOBG9"
},
"pod_url": "https://umbrella-dev.yojee.com/api/v3/public/pods/order_item/YOJ-VBBS9LFIOBG9",
"task_type": "dropoff"
},
"event_type": "task.completed",
"id": "4b067931-b83b-45f4-92ff-85c908a6f417",
"webhook_id": 96,
"yojee_instance": "https://umbrella-dev.yojee.com"
}
Task.Failed
{
"company_slug": "yojee",
"created_at": 1573619526,
"data": {
"driver": {
"id": 683,
"name": "Nikola Test Driver"
},
"event_time": "2019-11-13T04:31:09.000000Z",
"id": 35854,
"inserted_at": "2019-11-13T04:29:51.353982Z",
"order_item": {
"external_customer_id": null,
"external_customer_id2": null,
"external_customer_id3": null,
"tracking_number": "YOJ-MDMSLHECUDWP"
},
"task_type": "pickup"
},
"event_type": "task.failed",
"id": "730d3078-7c55-4afe-a90d-890f64545a9b",
"webhook_id": 96,
"yojee_instance": "https://umbrella-dev.yojee.com"
}