Webhooks API

The webhooks API lets you configure HTTP endpoints that receive real-time notifications when an order moves through Shippit's shipping states.

A merchant can have at most 6 webhooks. Each webhook targets a URL and fires only for the order states you specify.

There are two types of webhook available, one which maps status information from the carrier to the standard Shippit statuses, and one which returns the raw data without mapping. Both webhooks return data in in JSON format using snake_case. Only the mapped data webhook has endpoints available for you to query directly.

For more information about declaring the URL to use for your webhook, and other webhook settings, see the Webhooks section in the Developer guide.

Endpoints

GET/merchants/webhooksList the webhooks configured for your account
POST/merchants/webhooksCreate a webhook
PATCH/merchants/webhooks/:publishable_idUpdate a webhook
DELETE/merchants/webhooks/:publishable_idDelete a webhook
POST/webhookThe payload Shippit sends to your endpoint

The webhook object

publishable_idstring: Stable identifier for the webhook, prefixed twhs_.
webhook_urlstring: The URL receiving webhook events.
enabled_statesstring[]: Order states that trigger this webhook.
hide_delivery_addressboolean: Whether the payload omits the delivery address.
hide_receiver_detailsboolean: Whether the payload omits receiver details.
enabledboolean: Whether the webhook is currently active.
headersobject[]: Custom HTTP headers (key / value). Header values are always masked as *****.

Custom header values are always masked (*****) in all responses—they are write-only, and you can't retrieve them after creation.

Valid `enabled_states` values

order_placed
ready_for_pickup
in_transit
with_driver
delivery_attempted
awaiting_collection
await_collection
awaiting_drop_off
damaged
lost
insufficient_address
returned_to_sender
delivery_failed
with_customs
customs_on_hold
customs_awaiting_payment
customs_failed
return_booked
return_booking_failed
parcel_completed
partially_completed
cancelled
completed
return_requested
invalidated
pickup_failed
untrackable

Default request headers

Shippit always sends the following headers with every outgoing webhook request:

Header	Value
`Content-Type`	`application/json`
`Accept`	`application/json`

Any custom headers you configure are sent in addition to these defaults.

Reserved header keys

The following header keys are reserved and cannot be used as custom header keys:

host
content-length
content-type
connection
transfer-encoding
expect
proxy-authorization
upgrade
te
trailer

Attempting to use a reserved key will result in a validation error.

Sample responseJSON

{
  "webhooks": [
    {
      "publishable_id": "twhs_abc123xyz",
      "webhook_url": "https://example.com/shippit-webhook",
      "enabled_states": ["ready_for_pickup", "in_transit", "completed"],
      "hide_delivery_address": false,
      "hide_receiver_details": false,
      "enabled": true,
      "headers": [
        { "key": "X-Custom-Token", "value": "*****" }
      ]
    }
  ]
}

Retrieve webhooks

GET/merchants/webhooks

Returns all webhooks configured for the authenticated merchant.

The API returns all webhooks in a single array. It returns an empty array if no webhooks exist.

To perform this operation, authenticate with an authentication token.

There is no pagination—every webhook for the merchant comes back in the one array.

Response codes

Status	Meaning	Description
200	OK	Returns all webhooks configured for the authenticated merchant. Returns an empty array if no webhooks exist.
403	Forbidden	Returned when the API key doesn't match a valid merchant account, or the API secret is missing the permission this endpoint requires.
500	Internal Server Error	Returned when an unknown error occurs. May be returned if Shippit has trouble with the combination of the input or merchant account configuration.

Response

JSON

{
  "webhooks": [
    {
      "publishable_id": "twhs_abc123xyz",
      "webhook_url": "https://example.com/shippit-webhook",
      "enabled_states": ["ready_for_pickup", "in_transit", "completed"],
      "hide_delivery_address": false,
      "hide_receiver_details": false,
      "enabled": true,
      "headers": [
        { "key": "X-Custom-Token", "value": "*****" }
      ]
    },
    {
      "publishable_id": "twhs_def456uvw",
      "webhook_url": "https://example.com/another-webhook",
      "enabled_states": ["order_placed"],
      "hide_delivery_address": true,
      "hide_receiver_details": false,
      "enabled": false,
      "headers": []
    }
  ]
}

Create a webhook

POST/merchants/webhooks

Creates a new webhook for the authenticated merchant.

A merchant can have at most 6 webhooks.

To perform this operation, authenticate with an authentication token.

Parameters

webhook_urlstringRequired

The URL that receives webhook events. Must begin with http:// or https://. Max 2048 characters.

enabled_statesstring[]Required

The list of order states that trigger this webhook. Must contain at least one value. See valid states below.

hide_delivery_addressbooleanOptional

Omit the delivery address from webhook payloads. Defaults to false.

hide_receiver_detailsbooleanOptional

Omit receiver details from webhook payloads. Defaults to false.

enabledbooleanOptional

Whether the webhook is active. Defaults to true.

headersarray of objectsOptional

Custom HTTP headers to include in outgoing webhook requests. Max 6 headers. Header keys must be unique.

Show child attributesHide child attributes

keystringRequired: The header name. No whitespace allowed. Must be unique across all headers in the array.
valuestringRequired: The header value. Can't be empty.

Response codes

Status	Meaning	Description
201	Created	Webhook created successfully. Header values are always masked in the response.
403	Forbidden	Returned when the API key doesn't match a valid merchant account, or the API secret is missing the permission this endpoint requires.
422	Unprocessable Entity	The API returns this when validation fails. It returns only one error per request—validations run in order and short-circuit on the first failure.
500	Internal Server Error	Returned when an unknown error occurs. May be returned if Shippit has trouble with the combination of the input or merchant account configuration.

Validation errors

Returned when validation fails. All validation errors follow the same shape.

Trigger	Error Description
Merchant already has 6 webhooks	Maximum number of webhooks reached.
Webhook URL is blank or doesn't start with `http(s)://`	Please enter a valid URL starting with `http://` or `https://`
Webhook URL exceeds 2048 characters	Webhook URL must not exceed 2048 characters.
Enabled states is empty	Add minimum one enabled state.
Enabled states contains unknown values	One or more enabled states are invalid.
More than 6 headers provided	You can add up to 6 custom headers.
A header key is blank or contains whitespace	Please enter a valid key without whitespaces
A header value is blank	Header value can't be empty.
Duplicate header key	Header key can't be duplicated.

RequestJSON

{
  "webhook_url": "https://example.com/shippit-webhook",
  "enabled_states": ["ready_for_pickup", "in_transit", "completed"],
  "hide_delivery_address": false,
  "hide_receiver_details": false,
  "enabled": true,
  "headers": [
    { "key": "X-Custom-Token", "value": "abc123" }
  ]
}

Response

JSON

{
  "webhook": {
    "publishable_id": "twhs_abc123xyz",
    "webhook_url": "https://example.com/shippit-webhook",
    "enabled_states": ["ready_for_pickup", "in_transit", "completed"],
    "hide_delivery_address": false,
    "hide_receiver_details": false,
    "enabled": true,
    "headers": [
      { "key": "X-Custom-Token", "value": "*****" }
    ]
  }
}

Update a webhook

PATCH/merchants/webhooks/:publishable_id

Updates a webhook for the authenticated merchant.

Every field is optional—only the fields included are updated, and fields omitted from the request body stay unchanged.

To perform this operation, authenticate with an authentication token.

Parameters

publishable_idstringpathRequired: The publishable_id of the webhook to update (prefixed twhs_). Obtained from the GET or POST response.

All body fields are optional—only the fields you provide are updated, and omitted fields stay unchanged.

webhook_urlstringbodyOptional: New URL for the webhook. Must begin with http:// or https://. Max 2048 characters.
enabled_statesstring[]bodyOptional: Replaces the full list of order states. Must contain at least one value. Duplicates are silently removed. See valid states below.
hide_delivery_addressbooleanbodyOptional: Whether to omit the delivery address from webhook payloads.
hide_receiver_detailsbooleanbodyOptional: Whether to omit receiver details from webhook payloads.
enabledbooleanbodyOptional: Whether the webhook is active.
headersobject[]bodyOptional: Replaces all existing custom headers. Pass an empty array to remove all headers. Each object requires a key (string, no whitespace) and a value (string, non-empty). Max 6 headers, keys must be unique. Omit this field entirely to leave existing headers untouched.

Valid enabled_states values are listed under the webhook object.

Response codes

Status	Meaning	Description
200	OK	Webhook updated successfully. The API returns the full updated webhook. Header values are always masked.
403	Forbidden	Returned when the API key doesn't match a valid merchant account, or the API secret is missing the permission this endpoint requires.
404	Not Found	The API returns this when it couldn't find the given `publishable_id`.
422	Unprocessable Entity	Returned when validation fails. Only fields present in the request are validated.
500	Internal Server Error	Returned when an unknown error occurs. May be returned if Shippit has trouble with the combination of the input or merchant account configuration.

To perform this operation, authenticate with an authentication token.

Validation errors

Returned when validation fails. All validation errors follow the same shape.

Trigger	Error Description
Merchant already has 6 webhooks	Maximum number of webhooks reached.
Webhook URL is blank or doesn't start with `http(s)://`	Please enter a valid URL starting with `http://` or `https://`
Webhook URL exceeds 2048 characters	Webhook URL must not exceed 2048 characters.
Enabled states is empty	Add minimum one enabled state.
Enabled states contains unknown values	One or more enabled states are invalid.
More than 6 headers provided	You can add up to 6 custom headers.
A header key is blank or contains whitespace	Please enter a valid key without whitespaces
A header value is blank	Header value can't be empty.
Duplicate header key	Header key can't be duplicated.

RequestJSON

{
  "hide_delivery_address": false,
  "hide_receiver_details": false,
  "enabled": true
}

Response

JSON

{
  "response": {
    "publishable_id": "twhs_abc123xyz",
    "webhook_url": "https://new.example.com/hook",
    "enabled_states": ["in_transit", "completed", "delivery_attempted"],
    "hide_delivery_address": false,
    "hide_receiver_details": false,
    "enabled": true,
    "headers": [
      { "key": "X-New-Token", "value": "*****" }
    ]
  }
}

Delete a webhook

DELETE/merchants/webhooks/:publishable_id

Permanently deletes a webhook for the authenticated merchant.

Deletion is permanent—there is no soft delete or recovery.

A successful call returns a 204 with no response body.

To perform this operation, authenticate with an authentication token.

Parameters

publishable_idstringpathRequired: The publishable_id of the webhook to delete (prefixed twhs_).

No request body.

Response codes

Status	Meaning	Description
204	No Content	The webhook was permanently deleted. The API returns no response body.
403	Forbidden	Returned when the API key doesn't match a valid merchant account, or the API secret is missing the permission this endpoint requires.
404	Not Found	The API returns this when it couldn't find the given `publishable_id`.
500	Internal Server Error	Returned when an unknown error occurs. May be returned if Shippit has trouble with the combination of the input or merchant account configuration.

Response

JSON

{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

The webhook payload

POST/webhook

Shippit sends status updates on orders to a URL you have configured in your Shippit account. You can also add headers to this webhook, and choose which information to send across the webhook. Navigate to Settings → Webhooks to adjust your webhook settings.

This operation does not require authentication.

Payload fields

tracking_numberstringOptional

none

tracking_urlstringOptional

none

current_statestringOptional

Possible enumerations are await_collection, awaiting_collection, awaiting_drop_off, cancelled, completed, parcel_completed, partially_completed, customs_awaiting_paym, customs_failed, customs_on_hold, damaged, delivery_attempted, delivery_failed, in_transit, insufficient_address, invalidated, lost, pickup_failed, processing, ready_for_pickup, return_booked, return_booking_failed, return_requested, returned_to_sender, untrackable, with_customs, with_driver

retailer_order_numberstringOptional

none

courier_namestringOptional

none

courier_job_idstringOptional

none

delivery_addressstringOptional

none

delivery_suburbstringOptional

none

delivery_postcodestringOptional

none

delivery_statestringOptional

none

merchant_urlstringOptional

none

status_historyarray of objectsOptional

[The tracking history returned by the webhook]

Show child attributesHide child attributes

statusstringRequired: Order status
timestringRequired: Timestamp

productsarray of objectsOptional

none

Show child attributesHide child attributes

quantityinteger(int32)Optional: none
skustringOptional: none
titlestringOptional: none
product_line_idstringOptional: none

expected_delivery_datestringOptional

none

retailer_referencestringOptional

none

source_platformstringOptional

none

delivery_country_codestringOptional

none

delivery_latitudeintegerOptional

none

delivery_longitudeintegerOptional

none

delivery_instructionsstringOptional

none

Response codes

Your endpoint is expected to answer with:

Status	Meaning	Description
200	OK	The response (success) the webhook expects from your application endpoint.

PayloadJSON

{
  "tracking_number": "PPYvZCTod5bkD",
  "expected_delivery_date": "2016-04-26T20:46:01+10:00",
  "tracking_url": "http://app.shippit.com/tracking/ppyvzctod5bkd",
  "current_state": "completed",
  "retailer_order_number": "WEYFEW232",
  "retailer_reference": "#OD12345",
  "courier_name": "Couriers Please",
  "courier_job_id": "CPAVZUZ0001749",
  "delivery_address": "123 Fake Drive",
  "delivery_suburb": "Sydney",
  "delivery_postcode": "2000",
  "delivery_state": "NSW",
  "delivery_country_code": "AU",
  "delivery_latitude": -33.77,
  "delivery_longitude": 150.91,
  "merchant_url": "myshopify.storename.com",
  "status_history": [
    {
      "status": "completed",
      "time": "2016-04-26T19:36:32.000Z"
    },
    {
      "status": "with_driver",
      "time": "2016-04-26T18:36:32.000Z"
    },
    {
      "status": "in_transit",
      "time": "2016-04-26T17:36:32.000Z"
    },
    {
      "status": "ready_for_pickup",
      "time": "2016-04-26T16:36:11.000Z"
    },
    {
      "status": "despatch_in_progress",
      "time": "2016-04-26T16:27:35.000Z"
    },
    {
      "status": "order_placed",
      "time": "2016-04-26T16:25:04.000Z"
    }
  ],
  "products": [
    {
      "quantity": 1,
      "sku": "EWPE123123",
      "title": "Super awesome red tshirt",
      "product_line_id": "1234"
    },
    {
      "quantity": 7,
      "sku": "EWPE123123",
      "title": "Super awesome blue tshirt",
      "product_line_id": "1235"
    }
  ]
}

Webhooks API

Endpoints

The webhook object

Valid enabled_states values

Default request headers

Reserved header keys

Retrieve webhooks

Response codes

Create a webhook

Parameters

Response codes

Validation errors

Update a webhook

Parameters

Response codes

Validation errors

Delete a webhook

Parameters

Response codes

The webhook payload

Payload fields

Response codes

Valid `enabled_states` values