Webhooks

Overview

Shipup provides a webhook system for sending shipping events of your orders directly to an endpoint on your server. This can be helpful when you want to do specific actions in reaction to shipping events.

📘

The data specification of webhook events can be found in Shipup's webhook API specification

First, you will need to configure your webhook endpoint. Webhook endpoint settings include the type of webhook events you want to receive and the URL that will receive those webhook events.

You can set up multiple webhook endpoints in order to receive webhook events on different URLs. Once your first webhook endpoint is created you will receive the selected webhook events via an HTTP POST request on the configured URL.

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 Shipup that you did not receive the webhook. This does mean that a URL redirection or a "Not Modified" response will be treated as a failure. Shipup will ignore any other information returned in the request headers or request body. Also, your endpoint should respond within 10 seconds to the POST request.

Retry strategy

If a webhook POST request is not successful (i.e. the return code is not 2xx or you fail to acknowledge the notification before 10 seconds) the webhook event will be sent back, later on, using exponential backoff. In this situation, the retry_count field of the webhook event will be increased by one. The max retry count is 5, after that, the webhook event will be dropped.

Livemode and test data

Upon webhook endpoint creation or update, Shipup sends a test JSON payload to the specified URL to validate its availability:

{
  "livemode": "false"
}

Your endpoint should simply return a 200 status code to acknowledge the payload. Failing to do so will prevent webhook endpoint saving.
Additionaly, you can send test payloads from the Shipup webhook endpoint creation / edit interface. Those test payloads contain sample objects, close to production data. livemode is set to false for those test payloads.
All other webhook events have the livemode key set to true.