Setting Up Webhooks

ShipEngine allows you to subscribe to webhooks to receive real-time updates for long-running asynchronous operations. This is useful because it allows your application to move on to other work while the operation is running rather than being blocked until it completes.

It also allows ShipEngine to push updates to your application rather than having your application continually poll for updates. For example, you may subscribe to the track webhook event to automatically receive an update anytime a tracking event occurs. Rather than continually sending a request to the /v1/labels/:label_id/track endpoint to see if the tracking information has been updated since the last time you checked, you can subscribe to the track webhook event and ShipEngine will push the notification to your application via a webhook whenever the tracking details are updated.

If you're new to webhooks, you can read this guide for more information.

Configuring Webhooks

Before you can begin receiving webhooks, you must configure your ShipEngine account with the HTTP endpoints you'd like for the webhooks to be sent to. You can do this through the ShipEngine Dashboard or through the API.

Configure Using the Dashboard

Log into the ShipEngine Dashboard.
Select API Management.
Select the Webhooks tab.
You should see a screen similar to the following which lists all the types of events you can subscribe to. For each webhook type you wish to subscribe to, enter a unique, publicly accessible URL where you want the webhooks to be sent and toggle the Status option so that the webhook is active.
Don't forget to click the Save button.

API Dashboard

Configure Using the API

To configure a webhook using the API, you'll need to provide a url and an event that will trigger the webhook. You'll send this data in an HTTP POST request to /v1/environments/webhooks. You may only configure one URL per event.

Warning

HTTP 409 Conflict

If you create a webhook for an event that already exists, you'll receive an HTTP 409 Conflict error when your request is sent. If this occurs, be sure to review the list of webhooks, and delete the existing webhook for the event before resubmitting your request.

The payload for each type of webhook event will have a unique resource_type which indicates which type of event triggered the webhook. The event names you use in your payload when you configure a webhook through the API as well as the corresponding resource_type that will be sent in the webhook request for that event are listed below.

Description	`event`	`resource_type`
Batch completed	`batch`	`API_BATCH`
Shipment rate updated	`rate`	`API_RATE`
Any tracking event	`track`	`API_TRACK`
Carrier connected	`carrier_connected`	`API_CARRIER_CONNECTED`
Sales Orders imported (Beta)	`sales_orders_imported`	`API_SALES_ORDERS_IMPORTED`
Order Source refresh complete (Beta)	`order_source_refresh_complete`	`API_ORDER_SOURCE_REFRESH_COMPLETE`
A requested report is ready	`report_complete`	`API_REPORT_COMPLETE`

Example Request

POST /v1/environment/webhooks HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
  "url": "https://example.com/batch",
  "event": "batch"
}

curl -iX POST https://api.shipengine.com/v1/environment/webhooks \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-H 'Content-Type: application/json' \
-d '{
  "url": "https://example.com/batch",
  "event": "batch"
}'

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Host", "api.shipengine.com")
$headers.Add("API-Key", "__YOUR_API_KEY_HERE__")
$headers.Add("Content-Type", "application/json")

$body = "{`n  `"url`": `"https://example.com/batch`",`n  `"event`": `"batch`"`n}"

$response = Invoke-RestMethod 'https://api.shipengine.com/v1/environment/webhooks' -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json

var myHeaders = new Headers();
myHeaders.append("Host", "api.shipengine.com");
myHeaders.append("API-Key", "__YOUR_API_KEY_HERE__");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({"url":"https://example.com/batch","event":"batch"});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://api.shipengine.com/v1/environment/webhooks", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.shipengine.com/v1/environment/webhooks',
  'headers': {
    'Host': 'api.shipengine.com',
    'API-Key': '__YOUR_API_KEY_HERE__',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({"url":"https://example.com/batch","event":"batch"})

};
request(options, function (error, response) { 
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.shipengine.com/v1/environment/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS =>"{\n  \"url\": \"https://example.com/batch\",\n  \"event\": \"batch\"\n}",
  CURLOPT_HTTPHEADER => array(
    "Host: api.shipengine.com",
    "API-Key: __YOUR_API_KEY_HERE__",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests

url = "https://api.shipengine.com/v1/environment/webhooks"

payload = "{\n  \"url\": \"https://example.com/batch\",\n  \"event\": \"batch\"\n}"
headers = {
  'Host': 'api.shipengine.com',
  'API-Key': '__YOUR_API_KEY_HERE__',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data = payload)

print(response.text.encode('utf8'))

require "uri"
require "net/http"

url = URI("https://api.shipengine.com/v1/environment/webhooks")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Host"] = "api.shipengine.com"
request["API-Key"] = "__YOUR_API_KEY_HERE__"
request["Content-Type"] = "application/json"
request.body = "{\n  \"url\": \"https://example.com/batch\",\n  \"event\": \"batch\"\n}"

response = https.request(request)
puts response.read_body

var client = new RestClient("https://api.shipengine.com/v1/environment/webhooks");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Host", "api.shipengine.com");
request.AddHeader("API-Key", "__YOUR_API_KEY_HERE__");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"url\": \"https://example.com/batch\",\n  \"event\": \"batch\"\n}",  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"url\": \"https://example.com/batch\",\n  \"event\": \"batch\"\n}");
Request request = new Request.Builder()
  .url("https://api.shipengine.com/v1/environment/webhooks")
  .method("POST", body)
  .addHeader("Host", "api.shipengine.com")
  .addHeader("API-Key", "__YOUR_API_KEY_HERE__")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.shipengine.com/v1/environment/webhooks"
  method := "POST"

  payload := strings.NewReader("{\n  \"url\": \"https://example.com/batch\",\n  \"event\": \"batch\"\n}")

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
  }
  req.Header.Add("Host", "api.shipengine.com")
  req.Header.Add("API-Key", "__YOUR_API_KEY_HERE__")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

#import <Foundation/Foundation.h>

dispatch_semaphore_t sema = dispatch_semaphore_create(0);

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://api.shipengine.com/v1/environment/webhooks"]
  cachePolicy:NSURLRequestUseProtocolCachePolicy
  timeoutInterval:10.0];
NSDictionary *headers = @{
  @"Host": @"api.shipengine.com",
  @"API-Key": @"__YOUR_API_KEY_HERE__",
  @"Content-Type": @"application/json"
};

[request setAllHTTPHeaderFields:headers];
NSData *postData = [[NSData alloc] initWithData:[@"{\n  \"url\": \"https://example.com/batch\",\n  \"event\": \"batch\"\n}" dataUsingEncoding:NSUTF8StringEncoding]];
[request setHTTPBody:postData];

[request setHTTPMethod:@"POST"];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
  if (error) {
    NSLog(@"%@", error);
  } else {
    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
    NSError *parseError = nil;
    NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
    NSLog(@"%@",responseDictionary);
    dispatch_semaphore_signal(sema);
  }
}];
[dataTask resume];
dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);

import Foundation

var semaphore = DispatchSemaphore (value: 0)

let parameters = "{\n  \"url\": \"https://example.com/batch\",\n  \"event\": \"batch\"\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "https://api.shipengine.com/v1/environment/webhooks")!,timeoutInterval: Double.infinity)
request.addValue("api.shipengine.com", forHTTPHeaderField: "Host")
request.addValue("__YOUR_API_KEY_HERE__", forHTTPHeaderField: "API-Key")
request.addValue("application/json", forHTTPHeaderField: "Content-Type")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
  semaphore.signal()
}

task.resume()
semaphore.wait()

Testing Webhooks

You can use a service like requestbin.com to create temporary URLs to test webhooks. Any HTTP requests sent to that endpoint will be recorded with the associated payload and headers so you can observe the data sent from our webhooks before configuring your application to accept it.

Webhook Payloads

These are example payloads for the types of webhooks you can subscribe to. You can expect to receive a message with the same structure as these examples whenever you subscribe to the corresponding event. You'll notice that each payload includes a resource_type and a resource_url. Some payloads will contain additional information as well.

Example Batch Event Payload

{
  "resource_url": "https://api.shipengine.com/v1/batches/se-1013119",
  "resource_type": "API_BATCH"
}

{
  "resource_url": "https://api.shipengine.com/v1/batches/se-1013119",
  "resource_type": "API_BATCH"
}

Example Track Event Payload

{
  "resource_url": "https://api.shipengine.com/v1/tracking?carrier_code=usps&tracking_number=9400111298370264401222",
  "resource_type": "API_TRACK",
  "data": {
    "label_url": null,
    "tracking_number": "9400111298370264401222",
    "status_code": "IT",
    "status_description": "In Transit",
    "carrier_status_code": "NT",
    "carrier_status_description": "Your package is moving within the USPS network and is on track to be delivered the expected delivery date. It is currently in transit to the next facility.",
    "ship_date": "2020-06-30T16:09:00",
    "estimated_delivery_date": "2020-07-06T00:00:00",
    "actual_delivery_date": null,
    "exception_description": null,
    "events": [
      {
        "occurred_at": "2020-07-02T00:00:00Z",
        "carrier_occurred_at": "2020-07-02T00:00:00",
        "description": "In Transit, Arriving On Time",
        "city_locality": "",
        "state_province": "",
        "postal_code": "",
        "country_code": "",
        "company_name": "",
        "signer": "",
        "event_code": "NT",
        "latitude": null,
        "longitude": null
      },
      {
        "occurred_at": "2020-06-30T20:09:00Z",
        "carrier_occurred_at": "2020-06-30T16:09:00",
        "description": "Shipment Received, Package Acceptance Pending",
        "city_locality": "VERSAILLES",
        "state_province": "KY",
        "postal_code": "40383",
        "country_code": "",
        "company_name": "",
        "signer": "",
        "event_code": "TM",
        "latitude": 37.8614,
        "longitude": -84.6646
      }
    ]
  }
}

{
  "resource_url": "https://api.shipengine.com/v1/tracking?carrier_code=usps&tracking_number=9400111298370264401222",
  "resource_type": "API_TRACK",
  "data": {
    "label_url": null,
    "tracking_number": "9400111298370264401222",
    "status_code": "IT",
    "status_description": "In Transit",
    "carrier_status_code": "NT",
    "carrier_status_description": "Your package is moving within the USPS network and is on track to be delivered the expected delivery date. It is currently in transit to the next facility.",
    "ship_date": "2020-06-30T16:09:00",
    "estimated_delivery_date": "2020-07-06T00:00:00",
    "actual_delivery_date": null,
    "exception_description": null,
    "events": [
      {
        "occurred_at": "2020-07-02T00:00:00Z",
        "carrier_occurred_at": "2020-07-02T00:00:00",
        "description": "In Transit, Arriving On Time",
        "city_locality": "",
        "state_province": "",
        "postal_code": "",
        "country_code": "",
        "company_name": "",
        "signer": "",
        "event_code": "NT",
        "latitude": null,
        "longitude": null
      },
      {
        "occurred_at": "2020-06-30T20:09:00Z",
        "carrier_occurred_at": "2020-06-30T16:09:00",
        "description": "Shipment Received, Package Acceptance Pending",
        "city_locality": "VERSAILLES",
        "state_province": "KY",
        "postal_code": "40383",
        "country_code": "",
        "company_name": "",
        "signer": "",
        "event_code": "TM",
        "latitude": 37.8614,
        "longitude": -84.6646
      }
    ]
  }
}

Info

Event Timestamps

carrier_occurred_at is the timestamp of the event received from the carrier, it is assumed to be the local time of where the event occurred.

occurred_at is the UTC based time of the event's occurrence.

Warning The carried_occurred_at event property is not yet fully supported across all carriers.

Example Rate Event Payload

{
  "resource_url": "https://api.shipengine.com/v1/shipments/se-2120221/rates",
  "resource_type": "API_RATE"
}

{
  "resource_url": "https://api.shipengine.com/v1/shipments/se-2120221/rates",
  "resource_type": "API_RATE"
}

Example Carrier Connected Event Payload

{
  "resource_url": "https://api.shipengine.com/v1/carriers/se-1234",
  "resource_type": "API_CARRIER_CONNECTED"
}

{
  "resource_url": "https://api.shipengine.com/v1/carriers/se-1234",
  "resource_type": "API_CARRIER_CONNECTED"
}

Example Sales Order Imported Event Payload (Beta)

{
  "resource_url": "https://api.shipengine.com/v-beta/sales_orders",
  "resource_type": "API_SALES_ORDERS_IMPORTED",
  "data": [
  {
    "sales_order_id": "2078df4d-49c1-53da-837a-ad2781b782e0",
    "external_order_id": "611699195963",
    "external_order_number": "SH21622",
    "order_source":
      {
        "order_source_id": "4e4af80f-6974-48b6-b88f-e46f1c2a0b28",
        "order_source_nickname": "Shippity Shop Shopify",
        "order_source_code": "shopify",
        "order_source_friendly_name": "Shopify",
        "refresh_info":
        {
          "status": "idle",
          "last_refresh_attempt": "2018-09-12T19:29:21.657Z",
          "refresh_date": "2018-09-12T19:29:16.837Z"
        },
        "active": true
      },
      "sales_order_status":
      {
        "payment_status": "paid",
        "fulfillment_status": "unfulfilled",
        "is_cancelled": false
      },
      "order_date": "2018-09-12T19:18:12Z",
      "created_at": "2018-09-12T19:29:18.69Z",
      "modified_at": "2018-09-12T19:29:18.69Z",
      "payment_details":
      {
        "subtotal":
        {
          "currency": "usd",
          "amount": 40.0
        },
        "estimated_shipping":
        {
          "currency": "usd",
          "amount": 0.0
        },
        "estimated_tax":
        {
          "currency": "usd",
          "amount": 0.0
        },
        "grand_total":
        {
          "currency": "usd",
          "amount": 40.0
        }
      },
      "customer":
      {
        "name": "Amanda Miller",
        "phone": "555-555-5555",
        "email": "[email protected]"
      },
      "bill_to":
      {
        "email": "[email protected]",
        "address":
        {
          "name": null,
          "phone": null,
          "company_name": null,
          "address_line1": "",
          "address_line2": null,
          "address_line3": null,
          "city_locality": null,
          "state_province": null,
          "postal_code": null,
          "country_code": null,
          "address_residential_indicator": "no"
        }
      },
      "ship_to":
      {
        "name": "Amanda Miller",
        "phone": "555-555-5555",
        "address_line1": "525 S Winchester Blvd",
        "city_locality": "San Jose",
        "state_province": "CA",
        "postal_code": "95128",
        "country_code": "US",
        "address_residential_indicator": "yes"
      },
      "sales_order_items": [
      {
        "sales_order_item_id": "6f8f3f51-7a5a-50b2-a842-d6e89a5b5b26",
        "line_item_details":
        {
          "name": "Bubble Popper 4XL",
          "sku": "BUB-1-T",
          "weight":
          {
            "value": 2.8,
            "unit": "ounce"
          }
        },
        "ship_to":
        {
          "name": "Amanda Miller",
          "phone": "555-555-5555",
          "address_line1": "525 S Winchester Blvd",
          "city_locality": "San Jose",
          "state_province": "CA",
          "postal_code": "95128",
          "country_code": "US",
          "address_residential_indicator": "yes"
        },
        "requested_shipping_options":
        {
          "shipping_service": null,
          "ship_date": null
        },
        "price_summary":
        {
          "unit_price":
          {
            "currency": "usd",
            "amount": 40.0
          },
          "estimated_tax":
          {
            "currency": "usd",
            "amount": 0.0
          },
          "estimated_shipping": null,
          "total":
          {
            "currency": "usd",
            "amount": 40.0
          }
        },
        "quantity": 1,
        "is_gift": false
      }]
  }]
}

{
  "resource_url": "https://api.shipengine.com/v-beta/sales_orders",
  "resource_type": "API_SALES_ORDERS_IMPORTED",
  "data": [
  {
    "sales_order_id": "2078df4d-49c1-53da-837a-ad2781b782e0",
    "external_order_id": "611699195963",
    "external_order_number": "SH21622",
    "order_source":
      {
        "order_source_id": "4e4af80f-6974-48b6-b88f-e46f1c2a0b28",
        "order_source_nickname": "Shippity Shop Shopify",
        "order_source_code": "shopify",
        "order_source_friendly_name": "Shopify",
        "refresh_info":
        {
          "status": "idle",
          "last_refresh_attempt": "2018-09-12T19:29:21.657Z",
          "refresh_date": "2018-09-12T19:29:16.837Z"
        },
        "active": true
      },
      "sales_order_status":
      {
        "payment_status": "paid",
        "fulfillment_status": "unfulfilled",
        "is_cancelled": false
      },
      "order_date": "2018-09-12T19:18:12Z",
      "created_at": "2018-09-12T19:29:18.69Z",
      "modified_at": "2018-09-12T19:29:18.69Z",
      "payment_details":
      {
        "subtotal":
        {
          "currency": "usd",
          "amount": 40.0
        },
        "estimated_shipping":
        {
          "currency": "usd",
          "amount": 0.0
        },
        "estimated_tax":
        {
          "currency": "usd",
          "amount": 0.0
        },
        "grand_total":
        {
          "currency": "usd",
          "amount": 40.0
        }
      },
      "customer":
      {
        "name": "Amanda Miller",
        "phone": "555-555-5555",
        "email": "[email protected]"
      },
      "bill_to":
      {
        "email": "[email protected]",
        "address":
        {
          "name": null,
          "phone": null,
          "company_name": null,
          "address_line1": "",
          "address_line2": null,
          "address_line3": null,
          "city_locality": null,
          "state_province": null,
          "postal_code": null,
          "country_code": null,
          "address_residential_indicator": "no"
        }
      },
      "ship_to":
      {
        "name": "Amanda Miller",
        "phone": "555-555-5555",
        "address_line1": "525 S Winchester Blvd",
        "city_locality": "San Jose",
        "state_province": "CA",
        "postal_code": "95128",
        "country_code": "US",
        "address_residential_indicator": "yes"
      },
      "sales_order_items": [
      {
        "sales_order_item_id": "6f8f3f51-7a5a-50b2-a842-d6e89a5b5b26",
        "line_item_details":
        {
          "name": "Bubble Popper 4XL",
          "sku": "BUB-1-T",
          "weight":
          {
            "value": 2.8,
            "unit": "ounce"
          }
        },
        "ship_to":
        {
          "name": "Amanda Miller",
          "phone": "555-555-5555",
          "address_line1": "525 S Winchester Blvd",
          "city_locality": "San Jose",
          "state_province": "CA",
          "postal_code": "95128",
          "country_code": "US",
          "address_residential_indicator": "yes"
        },
        "requested_shipping_options":
        {
          "shipping_service": null,
          "ship_date": null
        },
        "price_summary":
        {
          "unit_price":
          {
            "currency": "usd",
            "amount": 40.0
          },
          "estimated_tax":
          {
            "currency": "usd",
            "amount": 0.0
          },
          "estimated_shipping": null,
          "total":
          {
            "currency": "usd",
            "amount": 40.0
          }
        },
        "quantity": 1,
        "is_gift": false
      }]
  }]
}

Example Order Source Refresh Complete Event (Beta)

{
  "resource_url": "https://api.shipengine.com/v-beta/stores/se-0bdf1f26-5708-4e0b-a548-fd2a5720779f",
  "resource_type": "API_ORDER_SOURCE_REFRESH_COMPLETE"
}

{
  "resource_url": "https://api.shipengine.com/v-beta/stores/se-0bdf1f26-5708-4e0b-a548-fd2a5720779f",
  "resource_type": "API_ORDER_SOURCE_REFRESH_COMPLETE"
}

Example Report Complete Event Payload

{
  "resource_url": "https://api.shipengine.com/adjustments/se-0bdf1f26-5708-4e0b-a548-fd2a5720779f",
  "resource_type": "API_REPORT_COMPLETE"
}

{
  "resource_url": "https://api.shipengine.com/adjustments/se-0bdf1f26-5708-4e0b-a548-fd2a5720779f",
  "resource_type": "API_REPORT_COMPLETE"
}