logo
Documentation Powered by Redocly

Webhook partner API (1.2.0)

Download OpenAPI specification:Download

Webhook API specification of all supported endpoints that can be implemented on partner side to enable specified functionality. Such implemented and exposed endpoints can be registered in OXnet to get several types of notifications and reports. Endpoint URLs doesn't need to be according to specified paths, it is just example, it can be artibrary URL.

See also REST API definition of OXnet system.

Dictionary

Please take extra care about naming package vs. parcel. Package is a term we used in first version in OXnet, now we prefer parcel. On some places we still call it package to keep backward compatibility. Same is for driver vs. courier. Driver is older name for courier. Webhooks are newer name over callbacks.

Security

Endpoint security is something which is individual per partner and is not part of this API definition. Security is partially ensured by computing signatures (see 'ApiKeySignature' properties). Signature is computed from pre-defined part that is specified per endpoint functionality. It is defined per operations. Algorithm to encoding signature is something to be discussed individually. Standard endcoding is base64(sha256([data])), alternative encoding is lowercase(base64(sha256([data]))). Base64 encoding is applied on byte array of SHA256 hash, not its hexadecimal form. Example: content "parcel001superSECRETkey211231" will be encoded to "xI4S+9cM1QHXpRQ92hzJ9bvliStgDyo/kH9on4MwFBI=". Other encodings can be implemented in future.

Compatibility

Webhook API endpoints are about to change in future as the OXnet system is growing with new features. E.g. Adding new useful info about parcel entity can happen. In order to keep integrations running it is critical to have "ignore unknown" policy on receiving data. This is a strong recommendation to be able to throw away unknown properties in request body and/or unspecified custom HTTP headers. Compatible changes can be announced in some cases, but it is not necessary and the integration process cannot rely on announcements of compatible changes.

Webhook API incompatible changes will be avoided whenever it is possible with all technical and legal requirements. If some webhook API endpoint would need to be changed in an incompabible way it would be:

  • first early announced about why it is changed and how
  • API would be deprecated and kept for relevant time in order to provide smooth transition

Re-delivery

Time to live of notifications and reports is few hours. If endpoint is not responding within 30 seconds or fails with 4xx or 5xx HTTP code then it is automatically repeated. First few minutes it is retried several times as a try to deliver it as soon as possible. After initial few minutes the webhook is triggered once per few minutes.

Ordering

All notifications, events and reports contain timestamp information. Timestamp naturally orders the events. Depending on use case and combination of registered webhooks the timestamp should be considered.

For example, if all parcel changed are consumed then timestamp can be persisted in order to be able reject change events if they are delivered out of order.

Order of events cannot be secured by other mechanism because of re-delivery support and other technical reasons.

Parcel Notification

Parcel notifications (parcel stored, ...)

Notification fired when courier stores parcel into point

Notification body contains basic information about parcel, notification event time. Successful result is any of specified 2xx HTTP codes. Any 4xx or 5xx will be retried.

Request Body schema: application/json

Basic info about stored parcel

packageId
required
string <uuid> (ParcelId)

Parcel id

packageNumber
string (ParcelNumber)

External parcel number

pointId
string <uuid> (PointId)

Point id

storedBy
required
string
Value: "driver"

Constant: driver - Parcel had been successfully stored in the boxes by driver or any other type of courier

statusChangeEpochMillis
required
integer <int64> (Timestamp)

Event date and time in milliseconds since UNIX epoch

apiKeySignature
required
string

API key signature that secures callback endpoint. Signature is encoded according to API key encoding mode, the raw value for encoding is composition of "[packageNumber][defined API key][notification event date in UTC timezone in format YYMMDD]". API key is given by partner or is empty. API key signature should be verified at callback endpoint server.

Responses

Request samples

Content type
application/json
{
  • "packageId": "471cc1d4-ec27-4504-b7c2-949af95662bc",
  • "packageNumber": "string",
  • "pointId": "20a7be04-0667-469f-8fa4-da6cf02369c8",
  • "storedBy": "driver",
  • "statusChangeEpochMillis": 0,
  • "apiKeySignature": "string"
}

Notification fired when recipient successfully picks up the parcel from point

Notification body contains basic information about parcel, notification event time. Successful result is any of specified 2xx HTTP codes. Any 4xx or 5xx will be retried.

Request Body schema: application/json

Basic info about picked up parcel

packageId
required
string <uuid> (ParcelId)

Parcel id

packageNumber
string (ParcelNumber)

External parcel number

pointId
string <uuid> (PointId)

Point id

status
required
string
Value: "completed"

Constant: completed - Parcel had been successfully picked up by customer

statusChangeEpochMillis
required
integer <int64> (Timestamp)

Event date and time in milliseconds since UNIX epoch

apiKeySignature
required
string

API key signature that secures callback endpoint. Signature is encoded according to API key encoding mode, the raw value for encoding is composition of "[packageNumber][defined API key][notification event date in UTC timezone in format YYMMDD]". API key is given by partner or is empty. API key signature should be verified at callback endpoint server.

Responses

Request samples

Content type
application/json
{
  • "packageId": "471cc1d4-ec27-4504-b7c2-949af95662bc",
  • "packageNumber": "string",
  • "pointId": "20a7be04-0667-469f-8fa4-da6cf02369c8",
  • "status": "completed",
  • "statusChangeEpochMillis": 0,
  • "apiKeySignature": "string"
}

Notification fired when courier picks up the parcel from point because of overdue

Notification body contains basic information about parcel, notification event time. Successful result is any of specified 2xx HTTP codes. Any 4xx or 5xx will be retried.

Request Body schema: application/json

Basic info about displaced parcel

packageId
required
string <uuid> (ParcelId)

Parcel id

packageNumber
string (ParcelNumber)

External parcel number

pointId
string <uuid> (PointId)

Point id

status
required
string
Value: "displaced"

Constant: displaced - Parcel had been picked up by driver because of overdue

statusChangeEpochMillis
required
integer <int64> (Timestamp)

Event date and time in milliseconds since UNIX epoch

apiKeySignature
required
string

API key signature that secures callback endpoint. Signature is encoded according to API key encoding mode, the raw value for encoding is composition of "[packageNumber][defined API key][notification event date in UTC timezone in format YYMMDD]". API key is given by partner or is empty. API key signature should be verified at callback endpoint server.

Responses

Request samples

Content type
application/json
{
  • "packageId": "471cc1d4-ec27-4504-b7c2-949af95662bc",
  • "packageNumber": "string",
  • "pointId": "20a7be04-0667-469f-8fa4-da6cf02369c8",
  • "status": "displaced",
  • "statusChangeEpochMillis": 0,
  • "apiKeySignature": "string"
}

Notification fired when parcel is changed by any external or internal API call in context of vendor project

Notification body contains complete information about parcel that is available also on APIin context of vendor project, parcel change time. Successful result is any of specified 2xx HTTP codes. Any 4xx or 5xx will be retried. See also "carrierParcelChanged" operation.

Request Body schema: application/json

Complete info about changed parcel

required
object (Parcel)
timestamp
required
integer <int64> (Timestamp)

Event date and time in milliseconds since UNIX epoch

apiKeySignature
required
string

API key signature that secures callback endpoint. Signature is encoded according to API key encoding mode, the raw value for encoding is composition of "[JSON representation of parcel data][defined API key][notification event date in UTC timezone in format YYMMDD]". API key is given by partner or is empty. API key signature should be verified at callback endpoint server.

Responses

Request samples

Content type
application/json
{
  • "parcel": {
    },
  • "timestamp": 0,
  • "apiKeySignature": "string"
}

Notification fired when parcel is changed by any external or internal API call

Notification body contains complete information about parcel that is available also on API in context of carrier, info about courier id who stored or picked up parcel, payment data, parcel change time. Successful result is any of specified 2xx HTTP codes. Any 4xx or 5xx will be retried.

Request Body schema: application/json

Complete info about changed parcel

required
object (CarrierParcel)
timestamp
required
integer <int64> (Timestamp)

Event date and time in milliseconds since UNIX epoch

apiKeySignature
required
string

API key signature that secures callback endpoint. Signature is encoded according to API key encoding mode, the raw value for encoding is composition of "[JSON representation of parcel data][defined API key][notification event date in UTC timezone in format YYMMDD]". API key is given by partner or is empty. API key signature should be verified at callback endpoint server.

Responses

Request samples

Content type
application/json
{
  • "parcel": {
    },
  • "timestamp": 0,
  • "apiKeySignature": "string"
}

Parcel Report

Parcel reports (expired parcels, ...)

Report about expired parcels

Report is scheduled regularly. Report contains complete list of expired parcels. Each item of the report contains both internal and external parcel ID and point ID. Successful result is any of specified 2xx HTTP codes. Any 4xx or 5xx will be retried.

Request Body schema: application/json

Complete info about changed parcel

required
object
timestamp
required
integer <int64> (Timestamp)

Event date and time in milliseconds since UNIX epoch

apiKeySignature
required
string

API key signature that secures callback endpoint. Signature is encoded according to API key encoding mode, the raw value for encoding is composition of "[JSON representation of expired parcels][defined API key][notification event date in UTC timezone in format YYMMDD]". API key is given by partner or is empty. API key signature should be verified at callback endpoint server.

Responses

Request samples

Content type
application/json
{
  • "expiredParcels": {
    },
  • "timestamp": 0,
  • "apiKeySignature": "string"
}

Verification

Synchronous verifications (courier login, ...)

Verify courier by login credentials

Verification of courier is called during courier login. As a response courier identifier is expected, same identifier is then stored by OXnet system into parcel entity. Successful result is any of specified 2xx HTTP codes. Any 4xx or 5xx is considered as unsuccessful login.

Request Body schema: application/x-www-form-urlencoded

Report of expired parcels

username
required
string
password
required
string
pointId
string <uuid> (PointId)

Point id

timestamp
required
integer <int64> (EpochSeconds)

Time in epoch seconds

apiKeySignature
required
string

API key signature that secures callback endpoint. Signature is encoded according to API key encoding mode, the raw value for encoding is composition of "[username]:[password][defined API key][notification event date in UTC timezone in format YYMMDD]". API key is given by partner or is empty. API key signature should be verified at callback endpoint server.

Responses

Response samples

Content type
application/json
{
  • "id": "string"
}

Point Notification

Notification fired when point has been modified

Notification body contains complete information about point that is available also on API. Successful result is any of specified 2xx HTTP codes. Any 4xx or 5xx will be retried.

Request Body schema: application/json

Complete info about changed point

required
object (Point)

Point description

timestamp
required
integer <int64> (Timestamp)

Event date and time in milliseconds since UNIX epoch

apiKeySignature
required
string

API key signature that secures callback endpoint. Signature is encoded according to API key encoding mode, the raw value for encoding is composition of "[JSON representation of point data][defined API key][notification event date in UTC timezone in format YYMMDD]". API key is given by partner or is empty. API key signature should be verified at callback endpoint server.

Responses

Request samples

Content type
application/json
{
  • "point": {
    },
  • "timestamp": 0,
  • "apiKeySignature": "string"
}

Point Outage

Notification fired when point outage has been modified

Notification body contains complete information about point outage that is available also on API in context of point-outage. Successful result is any of specified 2xx HTTP codes. Any 4xx or 5xx will be retried.

Request Body schema: application/json

Complete info about changed point outage

required
object (PointOutage)
operation
required
string (PointOutageOperationEnum)
Enum: "CREATED" "EDITED" "DELETED"

Status:

  • CREATED - New point outage has been created
  • EDITED - Point outage has been edited
  • DELETED - Point outage has been deleted
timestamp
required
integer <int64> (Timestamp)

Event date and time in milliseconds since UNIX epoch

apiKeySignature
required
string

API key signature that secures callback endpoint. Signature is encoded according to API key encoding mode, the raw value for encoding is composition of "[JSON representation of pointOutage data][defined API key][notification event date in UTC timezone in format YYMMDD]". API key is given by partner or is empty. API key signature should be verified at callback endpoint server.

Responses

Request samples

Content type
application/json
{
  • "pointOutage": {
    },
  • "operation": "CREATED",
  • "timestamp": 0,
  • "apiKeySignature": "string"
}