Shipwell API

The Shipwell Developer Hub

Welcome to the Shipwell developer hub. You'll find comprehensive guides and documentation to help you start working with Shipwell API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Using Webhooks

How to configure and use webhooks

Configuring the endpoint

Learn how to set up webhook endpoints to receive events.

After building, testing, and deploying your webhook in the sandbox environment, set up the endpoint in production so Shipwell knows where to send events for which you are subscribed.

You can register webhook URLs for Shipwell to notify you any time an event happens in your account. When the event occurs—a milestone update on a Shipment, an invoice's status changes, —Shipwell creates an Event object.

This Event object contains all the relevant information about what just happened, including the type of event and the data associated with that event. Shipwell then makes an HTTP POST request to send the Event object to any endpoint URLs defined. (You define them in your account’s Webhooks settings.) You can have Shipwell send a single event to as many webhook endpoints as you desire.

Step 1: Configure webhook settings

Webhook endpoints are configured via the webhooks endpoints. You simply select the events you would like to trigger on and provide a URL.

Currently Support Event Types

Shipwell is constantly adding additional events. If you don't see an event that is currently supported that you need, please send an email to [email protected] with a description of the event and we will get back to you.

Step 2: Test your webhook

You can enter any URL as the destination for events. However, this should be a dedicated location on your server that is set up to receive webhook events. You can choose to be notified of all event types, or only specific ones.

Next, test that your endpoint is working properly. You can send test webhook events from the sandbox environment in Shipwell. Access your account and perform an action that would trigger the event.

Don't worry, sandbox data is not real data for customers, bills, invoices, or shipments or any other objects in your account. If your endpoint is working successfully, you’ll see the webhook get executed on your server. Additionally, you can call the Events API and look for the specific event you received.

Your current environment—whether you’re using the production or sandbox environment/APIs—determines whether test events or production events are sent to your configured URL. If you want to send both production and sandbox events to the same URL, you need to configure the separate Shipwell environments to both send their events to the same URL endpoint. Please note that this practice is strongly discouraged by Shipwell as it makes troubleshooting more difficult and it's easy for sandbox events to accidentally be mistaken as real events.

When your endpoint receives a request from Shipwell for a webhook, it will have two additional custom headers X-Shipwell-Signature and X-Shipwell-Timestamp. These two, in conjunction with the signing secret configured when setting up a webhook endpoint allow clients to verify that a request came from Shipwell. The X-Shipwell-Timestamp is an ISO-encoded timestamp of when Shipwell made the request to your server. The X-Shipwell-Signature is an HMAC sha256 hex-digest of the X-Shipwell-Timestamp header's contents, a semi-colon (;), and the body of the POST request concatenated together and converted to bytes. We strongly encourage using a cryptographically secure signing key when configuring your endpoints as well as having all endpoints verify the signature matchest the payload to ensure the request is authentically from Shipwell.

Step 3: Respond to webhook events

To acknowledge receipt of an event, your endpoint must return a 2xx HTTP status code. We encourage you to return a response back to the Shipwell server prior to executing any logic on the event since we impose a 10s timeout for webhook servers to respond. Your endpoint may be disabled if it fails to acknowledge any events over 7 consecutive days.

Timeouts and Retries

When an webhook is triggered, Shipwell will queue the event and webhook to be published. If the webhook is unsuccessful in delivering the event (the remote server was unreachable, returned a non 2xx HTTP response or the took longer than 10s to respond), the Publisher will attempt the webhook again after a 20 min initial retry wait. We'll attempt to deliver the webhook up to 5 times, doubling the delay between each attempt. If the webhook Publisher gives up, Shipwell will send an automatic email to the email address submitted when the webhook was configured.

Shipwell will automatically follow all redirects returned by the server, however we consider more than 30 redirections a failure. Additionally, the status code that we consider to determine if the webhook request succeeded or not is the last one received in the chain of redirections. Shipwell ignores any other information returned in the request headers or request body.

The majority of webhook issues result in 4xx and 5xx HTTP status codes. 4xx indicates Shipwell was able to contact your server, but the endpoint was not valid. Double-check that the endpoint URL is correct and able to receive POST requests. 5xx usually indicates an exception on your server was not handled properly.

Step 4: Go live

Once you’ve verified your endpoint is receiving, acknowledging, and handling events correctly, go through the configuration step again to configure an endpoint for your production integration. If you’re using the same endpoint for both sandbox and production modes, the signing secret is unique to each mode. Make sure to add the new signing secret to your endpoint code if you’re checking webhook signatures.

Updated 16 days ago

Using Webhooks


How to configure and use webhooks

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.