Skip to content

Webhooks

What is a Webhook?

A webhook is a lightweight, event-driven way for two applications to talk to each other over HTTP. It is a subscription mechanism that allows your application to receive notifications about events. Instead of your application pulling data on a schedule, InPost calls your server the moment something happens — for example, when a parcel is delivered.

To start using webhooks, see Integration guide for details.

Key Benefits of Webhooks

  • Near real-time updates — Data arrives as soon as an event occurs, without polling delays.
  • Reduced resource usage — No need to make repeated API calls to check for changes that have not occurred.
  • Scalability — Tracking many parcels via polling means many redundant calls what is inefficient and may trigger rate limits.

Retry mechanism

Your endpoint must respond with 200 OK to confirm a notification was received. Any other response (including a timeout) is treated as a failed delivery.

Failed deliveries are retried on this fixed schedule:

  • 1 time after 15 seconds, then
  • 1 time after 30 seconds, then
  • 1 time after 1 minute, then
  • 1 time after 5 minutes, then
  • 1 time after 30 minutes.

If your endpoint still hasn't returned 200 OK after this last attempt, the notification is marked as failed and no further attempts are made — there is no manual replay today, so an endpoint that is down for longer than ~35 minutes will permanently lose that notification.

Handling timeouts

Your webhook endpoint must return a 200 OK response promptly, as slow responses will be treated as failed deliveries and may lead to exhausted retries or endpoint suspension. We recommend:

  • monitoring your system response times,
  • processing time-consuming work asynchronously after acknowledging receipt.

Handling duplicated events

Response 200 OK can be lost on the way back to InPost, even after your server has fully processed a notification. Due to that InPost may run a retry mechanism and deliver an event, which your server already received. Create a mechanism to eliminate duplicates with x-inpost-event-id. If a duplicated event is received, the endpoint should treat it as a no operation and return 200 OK without reprocessing. See the headers reference for the full list of headers sent with every call.

Whitelisting IPs

Optionally you may whitelist InPost IPs for inbound traffic.

InPost sends webhook notifications from the CIDR range 119.12.18.0/24 and from the static IPs: 34.38.70.198, 34.14.4.150, 34.38.90.135, 35.190.208.173, 35.233.29.220, 34.38.96.97, 34.62.178.170, 34.79.177.13, 35.195.207.142, 35.205.107.171.

Notifications are sent to the default HTTP (80) and HTTPS (443) ports.

Webhook payload versioning

We might need to change the event payload after the system is live. If a change is non-breaking (e.g. a new field is added), no new version is introduced — your integration should ignore fields it doesn't recognize. If a change is breaking (e.g. a field is renamed or removed), a new version is introduced instead, and existing subscriptions keep receiving the version they subscribed to.

Every webhook call carries the payload version in the x-inpost-api-version header, formatted as a date, e.g. 2024-06-01. See the headers reference for the full list of headers sent with every call.