Webhooks Overview

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

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

Before you can begin receiving webhooks, you must configure your account with the HTTP endpoints you'd like for the webhooks to be sent to.

For ShipStation users, you can do this through ShipStation or through the API.

For ShipStation API users, you can do this through the ShipStation API Dashboard or through the API.

You must be in the Production environment to set up webhooks.

If you use ShipStation (the web-based shipping platform), follow the instructions in the ShipStation Webhooks Help Article to configure webhooks through your ShipStation account.

If you use ShipStation API (formerly ShipEngine), you can configure webhooks through the ShipStation API Dashboard:

1. Log in to the ShipStation API Dashboard.
2. Go to Setup, then Webhooks.
3. Click the Create Webhook button.
4. Enter your Webhook Name, select your Webhook Event, select Order Source filters if desired, and enter your Webhook URL.
5. Click the green save button to save your webhook.

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 using the POST method to /v2/environment/webhooks.

You can configure multiple webhooks for the same event type, but each webhook must have a unique combination of url, event, and store_id (if provided). For example, you can have 5 tracking webhooks as long as they target different listener URLs or monitor different store_id values.

The payload for each type of webhook event will have a unique resource_type which indicates which type of event triggered the webhook.

ShipStation API v2 webhook events have enhanced payload structures and can only be created through the API endpoint (POST /v2/environment/webhooks).

This example uses a batch_processed_v2 event.

POST /v2/environment/webhooks

curl -i -X POST \
  https://api.shipstation.com/v2/environment/webhooks \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "name": "My New Webhook",
    "event": "batch",
    "url": "https://example.com/station/events",
    "headers": [
      {
        "key": "custom-key",
        "value": "custom-value"
      }
    ],
    "store_id": 123456
  }'

## Testing Webhooks

You can use a service like [Webhook.site](https://webhook.site/) to create temporary URLs to receive webhooks.
It will allow you to observe any HTTP requests the temporary URL receives. This will allow you to see the exact
payload and headers sent from our system, before your application is ready to accept it.
Make sure to unregister the webhook after your testing is complete.

## Delivery & Retry Logic

When ShipStation API dispatches a webhook, we allow 10 seconds for you to acknowledge you have successfully received the payload (your listener should return a 2xx response to us). If we don't receive an acknowledgement within 10 seconds, the system will put the payload back into the queue and make a maximum of **two additional attempts** to dispatch the given payload. These attempts are typically separated by 30 minutes. However, this can swap to other timing intervals under certain conditions. If all three attempts receive no response, the event will be removed from the dispatch queue.

## Next Steps

- [Webhook Validation](/apis/@shipstation-v2/docs/guides/webhooks-validation.md) - Learn how to validate webhook signatures for security
- [Webhook Schemas](/apis/@shipstation-v2/docs/guides/webhooks-schemas.md) - See payload examples for all webhook events