> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.ship24.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Setting Up Webhooks for the Tracking API

### Introduction

Webhooks push tracking updates to your system as soon as Ship24 finds them, so you do not have to keep asking whether anything has changed.

This article covers configuring webhooks in your dashboard and the behaviour you need to handle. For payload structure and field definitions, see the [webhook documentation](https://docs.ship24.com/webhooks/overview). If you have not set up your API key yet, start with [getting started with the Ship24 Tracking API](https://help.ship24.com/en/article/getting-started-with-the-ship24-tracking-api-m8s3iw/).

### In this article

* [What your endpoint must do](#3-what-your-endpoint-must-do)
* [Configure your webhook URL](#3-configure-your-webhook-url)
* [Verify requests come from Ship24](#3-verify-requests-come-from-ship24)
* [Behaviour you need to handle](#3-behaviour-you-need-to-handle)
* [When updates go missing](#3-when-updates-go-missing)

### What your endpoint must do

Your endpoint has to answer two HTTP methods.

**HEAD.** Ship24 probes your endpoint with a HEAD request to check it is ready. Return `200 OK` with no body.

**POST.** Ship24 delivers tracking updates by POST. Return any status code in the `2xx` range. The body of your response is not used.

||| If your endpoint does not return `200 OK` to a HEAD request, you will not be able to save your webhook URL at all. This is the most common reason a setup fails at the first step.

### Configure your webhook URL

1. Go to [Integrations, Webhook](https://dashboard.ship24.com/integrations/webhook/) in your dashboard.
2. Enter your endpoint URL.
3. Use **Test your integration** to send a sample payload.
4. Save.

Once saved, updates flow automatically for every tracker you create. There is nothing to enable per shipment.

|| Webhooks only fire for shipments that have an active tracker. If you are using direct lookups rather than trackers, there is nothing for Ship24 to push.

### Verify requests come from Ship24

Ship24 allocates your account a webhook secret, visible in your dashboard, and sends it with every request:

```
Authorization: Bearer your_webhook_secret
```

Compare that value against your own copy before processing a payload. This is optional and worth doing, since your endpoint is a public URL that anyone could post to.

Ship24 also publishes the [outgoing IP addresses](https://docs.ship24.com/webhooks/delivery#webhooks-outgoing-ips) it sends from, if your infrastructure restricts inbound traffic.

||| Requests from **Test your integration** do not come from those published IPs. Set up and save your webhook URL before applying any IP restriction, or you will lock out your own test.

### Behaviour you need to handle

**Updates can arrive out of order.** Webhooks are not guaranteed to arrive in the order events happened. A retried message, or a courier releasing information late, can deliver an older event after a newer one. Always compare the event date in the message against the latest event you already hold before changing a shipment's status. Skipping this is the most common cause of shipments appearing to move backwards.

**Failures are retried.** If Ship24 does not receive a `2xx`, it retries up to 20 times with exponential backoff, from a few seconds out to a few hours. A brief outage on your side does not lose data.

**Retries mean repeats.** Because a message can be delivered more than once, process updates idempotently. Match on the event identifier and ignore anything you have already stored.

**Message grouping is configurable.** By default each message carries a single update, which is simplest to process. Higher grouping is available on request but introduces a delay of around 15 minutes while Ship24 waits for updates to group, so only ask for it if message volume is a genuine problem.

### When updates go missing

**Ask for a resend.** Ship24 can resend every webhook message for a given tracker, through the [resend endpoint](https://docs.ship24.com/tracking-api-reference/). Useful after an outage, or when you need to reprocess.

**Check the delivery history.** You can export the full webhook history for a shipment as a JSON file, from your dashboard or through the API. It lists every attempt Ship24 made, with status codes, timestamps, and the complete request and response, which usually shows immediately whether the problem is on your side or ours.

For everything else, see [troubleshooting the Tracking API](https://help.ship24.com/en/article/troubleshooting-the-tracking-api-1wsnop6/).

### Next steps

For the full specification of the webhook payload, see the [webhook documentation](https://docs.ship24.com/webhooks/specification). To understand the statuses arriving in your payloads, see [understanding shipment delivery statuses](https://help.ship24.com/en/article/understanding-shipment-delivery-statuses-1rikrd6/).