skills/ship24-webhooks/references/webhook-payloads.md

<!-- GENERATED by scripts/generate-references.mjs from spec/ship24-tracking-api.yaml. Do not edit; run pnpm generate. -->

# Ship24 webhook payloads

### Receive webhooks - Tracking results (`receive-webhooks-tracking-results`)

> This endpoint is **NOT** part of the Ship24 API but rather **has to be implemented on your side** in order to receive webhook messages.
Ship24 will be pushing tracking results to your endpoint using a `trackings` array containing `tracking` objects. The `tracking` object is detailed below as well as in [Schemas > Tracking](https://docs.ship24.com/tracking-api-reference/#/schemas/tracking). [Learn how to set up and use webhooks](https://docs.ship24.com/webhooks/overview).

> Note: `shipment.delivery.aiPredictiveDeliveryDate` is an [optional field](https://docs.ship24.com/data-format#optional-fields-add-on-options) and is absent from the payload unless you subscribed to its related add-on option.

Topic: `tracking/events`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| trackings[].metadata | metadata | no |  |
| trackings[].tracker | webhook-tracker | no |  |
| trackings[].shipment | shipment | no |  |
| trackings[].events | event[] | no |  |
| trackings[].statistics | statistics | no |  |

```json
{
  "trackings": [
    {
      "metadata": {
        "generatedAt": "2025-03-04T17:13:35.000Z",
        "messageId": "356a7f93-3ce5-4b49-b560-156537283df9",
        "topic": "tracking/events"
      },
      "tracker": {
        "trackerId": "26148317-7502-d3ac-44a9-546d240ac0dd",
        "trackingNumber": "9400115901047177598206",
        "shipmentReference": "c6e4fef4-a816-b68f-4024-3b7e4c5a9f81",
        "clientTrackerId": "3fa99515-3ca0-4901-85bb-056ee016799b",
        "isSubscribed": true,
        "createdAt": "2025-03-01T03:16:22.000Z"
      },
      "shipment": {
        "shipmentId": "f4f888d7-d140-423f-9a48-e0689d27e098",
        "statusCode": "delivery_delivered",
        "statusCategory": "delivery",
        "statusMilestone": "delivered",
        "originCountryCode": "US",
        "destinationCountryCode": "CN",
        "delivery": {
          "estimatedDeliveryDate": "2025-03-04T18:00:00",
          "courierEstimatedDeliveryDate": {
            "from": "2025-03-04T17:00:00",
            "to": "2025-03-04T18:00:00"
          },
          "service": null,
          "signedBy": null
        },
        "trackingNumbers": [
          {
            "tn": "9400115901047177598206"
          },
          {
            "tn": "9400111202544843610364"
          }
        ],
        "recipient": {
          "name": null,
          "address": null,
          "postCode": "94901",
          "city": null,
          "subdivision": null
        }
      },
      "events": [
        {
          "eventId": "ee8ebe96-4eae-4a91-9a99-8f3afa6a0f46",
          "trackingNumber": "9400111202544843610364",
          "eventTrackingNumber": "9400111202544843610364",
          "status": "Delivered to the addressee",
          "occurrenceDatetime": "2025-03-04T17:12:57",
          "order": 9,
          "location": "SAN RAFAEL, CA 94901",
          "sourceCode": "usps-tracking",
          "courierCode": "us-post",
          "statusCode": "delivery_delivered",
          "statusCategory": "delivery",
          "statusMilestone": "delivered",
          "hasNoTime": false,
          "utcOffset": null,
          "datetime": "2025-03-04T17:12:57.000Z"
        }
      ],
      "statistics": {
        "timestamps": {
          "infoReceivedDatetime": "2025-03-02T15:38:57",
          "inTransitDatetime": "2025-03-02T15:38:57",
          "outForDeliveryDatetime": "2025-03-04T10:12:57",
          "failedAttemptDatetime": null,
          "availableForPickupDatetime": null,
          "exceptionDatetime": null,
          "deliveredDatetime": "2025-03-04T17:12:57"
        }
      }
    }
  ]
}
```

### Receive webhooks - Proof of Delivery (`receive-webhooks-proof-of-delivery`)

> This endpoint is **NOT** part of the Ship24 API but rather **has to be implemented on your side** in order to receive webhook messages.
Ship24 pushes the proof of delivery of a shipment once retrieved from the courier, using a `trackings` array that always contains a single `tracking` object. [Learn more about Proof of Delivery webhooks](https://docs.ship24.com/webhooks/proof-of-delivery).

> 🛑 Requires the **Proof of Delivery** add-on option ([Subscriptions](https://dashboard.ship24.com/general/subscriptions)) and a _Proof of Delivery Webhook URL_ [configured in your dashboard](https://dashboard.ship24.com/integrations/webhook/).

Topic: `tracking/pod`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| trackings[].metadata | metadata | no |  |
| trackings[].tracker | webhook-tracker | no |  |
| trackings[].data | object | no |  |

```json
{
  "trackings": [
    {
      "metadata": {
        "generatedAt": "2025-03-05T09:41:12.000Z",
        "messageId": "8d1b3c1e-6a3f-4d2b-9f0e-2c7a1b5e9d44",
        "topic": "tracking/pod"
      },
      "tracker": {
        "trackerId": "26148317-7502-d3ac-44a9-546d240ac0dd",
        "trackingNumber": "1Z999AA10123456784",
        "shipmentReference": "c6e4fef4-a816-b68f-4024-3b7e4c5a9f81",
        "clientTrackerId": "3fa99515-3ca0-4901-85bb-056ee016799b",
        "isSubscribed": true,
        "createdAt": "2025-03-01T03:16:22.000Z"
      },
      "data": {
        "status": "found",
        "courier": "ups-tracking",
        "content": {
          "type": "application/pdf",
          "text": null,
          "downloadUrl": "<download_url>"
        }
      }
    }
  ]
}
```