1. Help Center
  2. API documentation

Step 8: Receive Webhooks on Updates to Your Items

This article is part of a 9-step guide to the Yojee API

"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"

}