About

What is a Webhook?

A Webhook is a lightweight, event-driven communication that automatically sends data between applications via HTTP.
To set up a webhook, the merchant provides URL to the server and specifies which events it wants to know about. Once the webhook is set up, the merchant no longer needs to poll the server, as the server will automatically send the relevant payload to the merchant’s webhook URL when the specified event occurs.

How to provide your URL to InPost?

Please contact InPost Account Manager and/or Integration Team. Self-service portal is under development.
During setup you will be requested to select event types you want to subscribe for.

How to authenticate and verify a payload?

No authentication mechanism will be enforced. Instead, webhook HTTP requests will be signed, and it is strongly recommended that consumers implement request validation to prevent external attacks on their exposed webhook endpoint. All supported authentication mechanisms are described in few below sections:

Basic Authentication

Standard HTTP basic access authentication, uses the Authentication header to provide a user name and password: Authorization: Basic <credentials>, where <credentials> is the Base64 encoding of the user name and password separated by a colon (:). To use this method of authentication client has to provide following information:

user name
password

API Key / Custom headers

A security key previously shared between both parties is passed in each request as an HTTP header, e.g., x-api-key. The header name can be customized, and multiple headers can be set, if needed. To use this method of authentication client has to provide following information for every custom header:

custom header name (e.g.: x-api-key)
custom header value (value of API Key/security key)

Webhook signature

A signature will be generated based on event payload using a Digital/HMAC signing mechanism, which can be configurable per client. Payload to sign can be created in two ways which also can be configurable per client:

event payload (the request body)
concatenated request timestamp header (x-inpost-timestamp) and event payload ("." - dot sign will be a separator).

This payload before signing is transformed from String to byte[] using standard UTF_8 charset encoding. The calculated signature will be transformed from byte[] to Base64 and then placed in the x-inpost-signature header

We are supporting two methods of signing webhooks:

To use this method of authentication client has to choose:

the type of signing body (only body or timestamp + body)
the type of signature (digital signature or HMAC signature)
- if digital signature chosen, then to verify signature client should use InPost public key provided in section Webhook Signature Verification
- if HMAC signature chosen, client should securely provide HMAC shared secret key which will be used by both parties to create and verify signature

Versioning

We might need to introduce changes to the event payload after the system is up and running. If these changes are non-breaking (e.g. a new field is added to the payload), no new version will be generated. But, if we need to introduce a breaking change (e.g. renaming or removing an existing field), then a new version will be introduced to ensure backwards compatibility of existing subscriptions. When a merchant subscribes to the webhook, they are subscribing to a specific version (typically the latest version at subscription time).

All webhook calls will identify the version of the payload being passed via a dedicated HTTP header, X-InPost-Api-Version, whose value takes the form a date, e.g. 2024-06-01.

Headers

Header	Example	Description
x-inpost-api-version	2024-06-01	Version of the payload being used in the request
x-inpost-topic	Shipment.Tracking	All tracking events will have topic set to “Shipment.Tracking”
x-inpost-event-id	XXX123	Unique id of the event
x-inpost-timestamp	2024-04-26T14:00:03.165Z	Date and Time when the webhook event is sent, in UTC
x-inpost-signature	XXXXXXX12345	Signature of the request