Přeskočit na hlavní obsah
For any questions, feel free to contact our integrations team at integrations@packeta.com

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
note

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​

HeaderDescriptionExample
Content-TypeStandard HTTP header.application/json
X-Webhook-TimestampUnix seconds when the request was signed (integer as string).1749837600
X-Webhook-Signaturehash_hmac('sha256', "{timestamp}.{rawBody}", key)9f4b1d…e2a
X-Webhook-VersionWebhook contract version.v1
X-Webhook-Event-IdUUID4 of the event. Use for receiver-side deduplication. Not part of the signed material.4c93637a-6904-4252-a7e2-520eb2d754

Security and message verification​

Algorithm​

  1. Read X-Webhook-Timestamp and X-Webhook-Signature from request headers.
  2. Read the raw request body — do not parse, normalize, re-serialize, or strip whitespace before verifying. The byte sequence must equal what was signed.
  3. Concatenate timestamp and raw request body using dot as the delimiter. Example: timestamp + '.' + rawJsonBody.
    • Hint: expected = hash_hmac('sha256', timestampHeader + '.' + rawBody, key)
  4. Encode the resulting string with the HMAC algorithm (using your Signing Key as a key and SHA256 digest mode).
    • Hint: Compare expected to X-Webhook-Signature with a constant-time comparison (hash_equals / crypto.timingSafeEqual / hmac.compare_digest).
  5. Reject the request if comparison fails.
  6. Only after the signature passes, you may use X-Webhook-Event-Id for deduplication.

Example signature verification​

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)

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
}
}
ClassPropertyDescriptionTypeNullable
statuseventIdID of the event (note: not the webhook)stringNo
statusidPacket barcode without 'Z' prefixintNo
statusbarcodeFull packet barcodestringNo
statusdateTimeLike ISO 8601, but the timezone is not mandatorystringNo
statusbranchIdBranch that generated the eventintYes
statusstatusIdID of status based on our documentationintNo
statusstatusCodeCode of the status in a string formstringNo
statusstatusTextText of the event. Not intended for machine processing!stringNo
statusexternalTrackingCodeCode of external carrier (usually used when handing packet to that carrier)stringYes
statusdestinationBranchIdID of branch that is meant as a destinationintYes

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"
}
}
ClassPropertyDescriptionTypeNullable
statuseventIdID of the event (note: not the webhook)stringNo
statusidPacket barcode without 'Z' prefixintNo
statusbarcodeFull packet barcodestringNo
statusdateTimeLike ISO 8601, but the timezone is not mandatorystringNo
statusbranchIdBranch that generated the eventintNo
statusexternalStatusIdID of status from external carrierstringNo
statusexternalStatusCodeCode of the status from the external carrierstringYes
statusexternalStatusTextText of the event from external carrier. Not intended for machine processing!stringYes
statusexternalTrackingCodeCode of external carrierstringNo

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.

info

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.