What are webhooks?

Webhooks put simply are event notifications (communicated via HTTP POST).

They are a way to provide other applications (such as an ERP, WMS or Invoicing system) with notifications as to when certain events have taken place.

These alerts can be used to trigger further actions in the other applications. One example would be Warehouse Management system being notified, by webhook, when an order has been planned for delivery, so picking can begin in the warehouse.

A webhook provides alerts (with some key data) to other applications as it happens, meaning the other applications get alerted in real time when the webhook events you want to know about (have subscribed to) take place.

You can send webhooks when specific events occur against your orders, items, deliveries, collections or runs.

Create a Stream Webhook Subscription

The first step for each Webhook is to use the Webhooks POST endpoint to subscribe to an event so that you can be informed when a certain event happens.

When subscribed, each time that particular event occurs , a webhook notification will be sent to the URL you specify in the subscription (shown as {Your URL path} in the examples below). The URL is used to listen out for notifications. The listening service could be something you have developed or a service available in your application.

Below are examples of, how to create subscriptions to some of our Webhooks. Our API documentation has more information on using Webhooks, including a full list of webhook events that can be subscribed to – you can view our Webhook API documentation here.

Order Delivered webhook

A webhook subscription to the DELIVERED event provides alerts when an order has been fully delivered.

To subscribe to this webhook make a POST request, as below, to: https://www.go2stream.net/api/webhooks/webhooks

POST request

{ 
"event": "DELIVERED", 
"event_type": "CONSHEADER", 
"url_path": "{Your URL path}", 
"http_method": "POST", 
"content_type": "application/json" 
}

Retrieving details of a ‘Delivered’ order

When an order has been fully delivered, the following webhook response will be received containing some key information relating to the event occurring.

For example, when the event occurred (event_date, event_time), and the related order (order id).

Example Response:

{
  "webhook": {
    "subscription": {
      "party_id": "JOSHC000000000001",
      "id": 3,
      "event": "DELIVERED",
      "event_type": "CONSHEADER",
      "url_path": "<strong>{Your URL path}</strong>",
      "http_method": "POST"
    },
    "event": {
      "event_code": "DELIVERED",
      "event_code_desc": "",
      "event_desc": "Status Updated To DELIVERED",
      "event_date": "20231122",
      "event_time": "144453",
      "event_text": "",
      "event_link": ""
    },
    "order": {
      "id": "JOSHC000000000563"
    }
  }
}

Delivery Failed Webhook:

A webhook subscription to the DELIVERYFAILED event provides alerts when an order fails delivery (for a delivery group/leg).

POST request

To subscribe to this webhook make a POST request, as below, to: https://www.go2stream.net/api/webhooks/webhooks

{
"event": "DELIVERYFAILED",
"event_type": "LOADALLOC",
"url_path": "<strong>{Your URL path}</strong>",
"http_method": "POST",
"content_type": "application/json"
}

Retrieving details of a ‘Failed’ delivery

When a delivery has failed, the following webhook response will be received containing key information relating to the event occurring.

For example, when the event occurred (event_date, event_time), why the delivery failed (event_desc), and the related order (order id).

Example Response: 

{
  "webhook": {
    "subscription": {
      "party_id": "JOSHC000000000001",
      "id": 4,
      "event": "DELIVERYFAILED",
      "event_type": "LOADALLOC",
      "url_path": "<strong>{Your URL path}</strong>",
      "http_method": "POST"
    },
    "event": {
      "event_code": "DELIVERYFAILED",
      "event_code_desc": "",
      "event_desc": "Did not reach location",
      "event_date": "20231122",
      "event_time": "144745",
      "event_text": "",
      "event_link": ""
    },
    "order": {
      "id": "JOSHC000000000564"
    },
    "group": {
      "int_seq": 1,
      "loadId": "LOADS000000095019"
    },
    "run": {
      "loadId": "",
      "status": "",
      "description": ""
    }
  }
}

Photo Capture Webhook

A webhook subscription to the TAKEPHOTO event is needed to be alerted when photos have been captured and if required, to be able to retrieve the photo image.

POST request

To subscribe to this webhook make a POST request, as below, to: https://www.go2stream.net/api/webhooks/webhooks

{
"event": "TAKEPHOTO",
"event_type": "LOADALLOC",
"url_path": "<strong>{Your URL path}</strong>",
"http_method": "POST",
"content_type": "application/json"
}

Retrieving photo details

When a photo has been captured the following webhook response will be received containing key information relating to the event occurring.

For example, when the event occurred (event_date, event_time), the related order (order id) and where the photo is stored (event_link).

The link/URL can be used to retrieve the photo from the cloud storage service.

Example Response

{
  "webhook": {
    "subscription": {
      "party_id": "JOSHC000000000001",
      "id": 1,
      "event": "TAKEPHOTO",
      "event_type": "LOADALLOC",
      "url_path": "<strong>{Your URL path}</strong>",
      "http_method": "POST"
    },
    "event": {
      "event_code": "TAKEPHOTO",
      "event_code_desc": "",
      "event_desc": "",
      "event_date": "20231121",
      "event_time": "105521",
      "event_text": "",
      "event_link": "https://storage.googleapis.com/stream-application-demo/images/2023/11/17005641226d55564a6e5a3472424854346e6d486c70784647744c47487249626234665032.jpeg"
    },
    "order": {
      "id": "JOSHC000000000423"
    },
    "group": {
      "int_seq": 1,
      "loadId": "LOADS000000094966"
    },
    "run": {
      "loadId": "",
      "status": "",
      "description": ""
    }
  }
}

Signature Capture Webhook:

A webhook subscription to the CAPTURESIGNATURE event is needed to be alerted when a signature has been captured and if required, to be able to retrieve the image of the signature.

POST request

Make a POST request to: https://www.go2stream.net/api/webhooks/webhooks

{
"event": "CAPTURESIGNATURE",
"event_type": "LOADALLOC",
"url_path": "<strong>{Your URL path}</strong>",
"http_method": "POST",
"content_type": "application/json"
}

Retrieving signature details

When a signature has been captured the following webhook response will be received containing key information relating to the event occurring.

For example, when the event occurred (event_date, event_time), the related order (order id) and where the signature is stored (event_link).

The link can be used to retrieve the signature from the cloud storage service.

Example Response

{
  "webhook": {
    "subscription": {
      "party_id": "JOSHC000000000001",
      "id": 2,
      "event": "CAPTURESIGNATURE",
      "event_type": "LOADALLOC",
      "url_path": "<strong>{Your URL path}</strong>",
      "http_method": "POST"
    },
    "event": {
      "event_code": "CAPTURESIGNATURE",
      "event_code_desc": "",
      "event_desc": "Josh",
      "event_date": "20231121",
      "event_time": "105550",
      "event_text": "",
      "event_link": "https://storage.googleapis.com/stream-application-demo/images/2023/11/1700564150556e79705579556a6f32725651656143496965727a4c30417570453248306971.png"
    },
    "order": {
      "id": "JOSHC000000000423"
    },
    "group": {
      "int_seq": 1,
      "loadId": "LOADS000000094966"
    },
    "run": {
      "loadId": "",
      "status": "",
      "description": ""
    }
  }
}