Skip to main content

Proof of Delivery

Proof of Delivery webhooks​

With the Proof of Delivery add-on option (Subscriptions), Ship24 retrieves the proof of delivery of your shipments from the courier once they are delivered and pushes it to your system by webhook. Proofs of delivery are only delivered by webhook: they are not part of the tracking results returned by the API.

How does it work?​

  • Trackers created after you subscribe automatically request a proof of delivery. Nothing changes in your API calls.
  • Once the shipment is delivered, Ship24 queries the courier for a proof of delivery, for the couriers that provide one.
  • When retrieved, one webhook message with topic tracking/pod is sent to your Proof of Delivery Webhook URL.

How to set it up?​

Configure a Proof of Delivery Webhook URL in your dashboard: without it, no proof of delivery webhook is sent. It is separate from your tracking results webhook URL and can point to the same endpoint or a different one. Both use the same Webhook Secret (Authentication) and the same retry behavior. Proof of delivery messages are never grouped: the trackings array always contains one item.

Message format​

The format is detailed in the API Reference. data.status is found when a proof of delivery was retrieved and unavailable when the courier returned none. The proof itself is in data.content, in one of two forms depending on content.type:

content.typeContent
text/plain, text/htmlSignatory name or delivery note in content.text.
application/pdf, image/png, image/jpegFile to download from content.downloadUrl.

downloadUrl is valid for 7 days. Download and store the file on your side as soon as you receive the message.

{
  "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>"
        }
      }
    }
  ]
}