Webhook

Documentation of webhook, we will use to validate customer package in AlzaPort process.

1 Introduction
2 Configuration
3 Endpoint
- 3.1 Request
- 3.2 Response
- 3.3 Status codes
4 Testing

Introduction

Customer, which would like to send a package using AlzaPort technology, prepares his package at home with printed barcode. Then he takes his package and brings to AlzaBox. He will use an AlzaBox scanner to read all information from barcode to AlzaBox itself. We need to validate this package, because there are several issues which could happen, e.g. package is dedicated for another AlzaBox. This validation is implemented by partners' webhooks. We ask our partner, whether given package is valid and suitable to insert into given AlzaBox. If yes, process is continued by opening an appropriate slot. If not, user is informed and process is finished.

Configuration

Information we need to configure a call to partner's webhook:

endpoint url
authentication kind
- we prefer sending bearer token in authorization header
- we are able to configure other security options

Endpoint

We will send a request using POST http method.

Request

The request format will be JSON body with these properties:

Property	Type	Description

Property	Type	Description
customerInput	string	Package identification from customer
boxId	int	Box identification
identificationSource	int	Identification of package source, currently these values are supported: Scanner - package has been scanned by scanner Manual - package identification has been inserted manually by user
cultureInfo	string	Selected language on AlzaBox as two-letter code List of ISO 639-1 codes - Wikipedia AlzaBoxes currently support these languages: cs, sk, hu, de, en

{
  "customerInput": "doc2",
  "boxId": 20,
  "identificationSource": 1,
  "cultureInfo": "cs"
}

Response

After valid response we open the slot for the customer and make the reservation.

Response format will be JSON body with these properties:

Property	Type	Required	Required for valid package	Description

Property	Type	Required	Required for valid package	Description
isValid	bool	true	true	Customer package is valid.
rejectionReason	string	false	false	Text message with a reason, why package is not valid.
localizedRejectionReason	string	false	false	Localized text message with a reason, why package is not valid. max. 150 characters
packageInfo	object	false	false	Additional information about a package.
docNumber	string	false	false	Identification of a reservation\parcel.
barcode	string	false	true	Identification of a package .

Format of a packageInfo object:

Property	Type	Required	Description

Property	Type	Required	Description
height	decimal	false	Height of a package in cm
width	decimal	false	Width of a package in cm
depth	decimal	false	Depth of a package in cm

{
	"isValid": true,
	"rejectionReason": null,
	"packageInfo": {
		"height": 10,
		"depth": 25,
		"width": 30
	},
	"docNumber" : "AVRA123456",
	"barcode": "987654321"
}

{
	"isValid": false,
	"rejectionReason": "unknown package",
	"localizedRejectionReason": "Neznámý balík"
	"packageInfo": null
}

Status codes

Default response status code should be 200 OK for both, valid and invalid packages. For missing or incorrect token should be response status code 401 Unauthorized.

Status code	When to return

Status code	When to return
200 OK	Package is valid or invalid.
401 Unauthorized	Token in request is missing or incorrect.

Testing

Since this process is initiated by customer in AlzaBox application, you can test your webhook implementation using VirtualBox. Just call Create customer reservation from VirtualBox - API Specification with specific barcode. It will simulate scanning the barcode on real AlzaBox and our backend is going to call configured webhook to verify the inlet package.