Push tracking service
Packeta offers to send real-time packet tracking status updates via HTTP POST requests to a webhook URL. This service is an alternative to the traditional web-based tracking interface that delivers the same tracking data directly to your systems.
Key Features
- Push events for packet status changes
- Secure and reliable delivery with retry logic
- JSON-formatted payloads for easy integration
How to activate the push tracking service
Contact the integration support team at integrations@packeta.com with the following information:
- A request to enable webhook subscriptions
- Your webhook URL (has to be HTTPS)
You will receive a generated Signing Key. Once your request is processed, you will begin receiving packet status updates at the specified endpoint.
General specifications
Webhook target response
When a Webhook POST is sent to the endpoint specified by you, Packeta expects the following HTTP status codes from your server and reacts accordingly:
- Success: 200 (OK), 202 (Accepted)
- Fail: Any other HTTP response code
If the receiving server does not return a successful HTTP status code, Packeta retries delivery using exponential backoff: 1 minute → 2 minutes → 4 minutes → 8 minutes and so on, up to 8 hours. After that, webhook delivery is paused until the issue on the recipient side is resolved. The application does not read the content of the reply.
Webhook specification
- Method:
POST - Delivery: one event per request
- Encoding:
UTF-8 - Body format:
JSON - Content-Type:
application/json
Request header
| Header | Description | Example |
|---|---|---|
Content-Type | Standard HTTP header. | application/json |
X-Webhook-Timestamp | Unix seconds when the request was signed (integer as string). | 1749837600 |
X-Webhook-Signature | hash_hmac('sha256', "{timestamp}.{rawBody}", key) | 9f4b1d…e2a |
X-Webhook-Version | Webhook contract version. | v1 |
X-Webhook-Event-Id | UUID4 of the event. Use for receiver-side deduplication. Not part of the signed material. | 4c93637a-6904-4252-a7e2-520eb2d754 |
Security and message verification
Algorithm
- Read
X-Webhook-TimestampandX-Webhook-Signaturefrom request headers. - Read the raw request body — do not parse, normalize, re-serialize, or strip whitespace before verifying. The byte sequence must equal what was signed.
- Concatenate timestamp and raw request body using dot as the delimiter. Example:
timestamp + '.' + rawJsonBody.- Hint: expected =
hash_hmac('sha256', timestampHeader + '.' + rawBody, key)
- Hint: expected =
- Encode the resulting string with the
HMACalgorithm (using your Signing Key as a key and SHA256 digest mode).- Hint: Compare expected to
X-Webhook-Signaturewith a constant-time comparison (hash_equals/crypto.timingSafeEqual/hmac.compare_digest).
- Hint: Compare expected to
- Reject the request if comparison fails.
- Only after the signature passes, you may use
X-Webhook-Event-Idfor deduplication.
Example signature verification
- Python
- PHP
import hmac, hashlib
def verify(raw_body: str, headers: dict, key: str) -> bool:
ts = headers.get('X-Webhook-Timestamp', '')
sig = headers.get('X-Webhook-Signature', '')
expected = hmac.new(key.encode(), f'{ts}.{raw_body}'.encode(), hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, sig)
<?php
// direct access is not safe, this is just a demonstration
$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$key = ... // from storage
$hmac = hash_hmac('sha256', $timestamp . '.' . $rawJsonBody, $key);
if (hash_equals($hmac, $signature)) {
// success
} else {
// fail
}
Event Types
Packeta Status Webhook
Contains statuses generated by Packeta.
{
"status": {
"eventId": "b109b7d3-5ec9-4904-a35f-bb42b150cd54",
"id": 1234567890,
"barcode": "Z1234567890",
"dateTime": "2016-07-25T12:00:00",
"branchId": 12,
"statusId": 2,
"statusCode": "arrived",
"statusText": "Packet arrived at branch.",
"externalTrackingCode": null,
"destinationBranchId": null
}
}
| Class | Property | Description | Type | Nullable |
|---|---|---|---|---|
status | eventId | ID of the event (note: not the webhook) | string | No |
status | id | Packet barcode without 'Z' prefix | int | No |
status | barcode | Full packet barcode | string | No |
status | dateTime | Like ISO 8601, but the timezone is not mandatory | string | No |
status | branchId | Branch that generated the event | int | Yes |
status | statusId | ID of status based on our documentation | int | No |
status | statusCode | Code of the status in a string form | string | No |
status | statusText | Text of the event. Not intended for machine processing! | string | No |
status | externalTrackingCode | Code of external carrier (usually used when handing packet to that carrier) | string | Yes |
status | destinationBranchId | ID of branch that is meant as a destination | int | Yes |
External Carrier Status Webhook
Contains data of external carrier.
{
"externalStatus": {
"eventId": "6e1a0ae8-b880-4277-8e51-aee0d90c18ef",
"id": 1234567890,
"barcode": "Z1234567890",
"dateTime": "2024-11-14T09:07:29",
"branchId": 4943,
"externalStatusId": "4",
"externalStatusCode": null,
"externalStatusText": "Vydanie balika kurierovi na dorucenie",
"externalTrackingCode": "12345678"
}
}
| Class | Property | Description | Type | Nullable |
|---|---|---|---|---|
status | eventId | ID of the event (note: not the webhook) | string | No |
status | id | Packet barcode without 'Z' prefix | int | No |
status | barcode | Full packet barcode | string | No |
status | dateTime | Like ISO 8601, but the timezone is not mandatory | string | No |
status | branchId | Branch that generated the event | int | No |
status | externalStatusId | ID of status from external carrier | string | No |
status | externalStatusCode | Code of the status from the external carrier | string | Yes |
status | externalStatusText | Text of the event from external carrier. Not intended for machine processing! | string | Yes |
status | externalTrackingCode | Code of external carrier | string | No |
Tracking status codes and date format
Date format
Date format is RFC 3339 (based on ISO 8601) and it is described in the status record table.
- General format:
YYYY-MM-DDTHH:MM:SSZ - With a time zone offset:
YYYY-MM-DDTHH:MM:SS±HH:MM
Examples:
- UTC time:
2025-06-19T15:47:00Z - With time zone offset:
2025-06-19T17:47:00+02:00
Status codes
The Tracking statuses are described in the status codes page.
To get the description of external carrier status codes, please visit the carrier’s documentation, or contact their technical support.
FAQ
How to change the webhook URL?
Currently webhook URL can’t be manually edited, please contact the integration support team at integrations@packeta.com.
Is there a sandbox or a test environment?
Currently there’s no test environment.
How to disable the push tracking?
Please contact our integration support team at integrations@packeta.com.