Webhooks Order Status Updates
Once the order has been created in Menu ecosystem, it is important to track the order status updates to notify the customer respectively.
This article explains how to register the custom ordering application to receive the order status updates and how to parse the response.
Before proceeding, you should have implemented:
Register for Webhook order status updates
The registration for webhook status updates can be done programmatically by going through the steps described below.
The implementation of the order status updates API adheres to stringent security measures to ensure the confidentiality and integrity of data in backend-to-backend communication, which is implemented on several levels and enforces machine to machine communication.
To proceed with setting up webhook configurations client_id
and client_secret will be provided by PAR Menu.
Generate Access Token
To establish a secure connection, client applications are provided with client_id and client_secret credentials, which are then used to generate access tokens. These access tokens serve as the authentication mechanism, guaranteeing that only authorized client applications can interact with the API.
By calling the /api/oauth/tokens the access token can be generated and later be used as the Bearer token for sending the webhook configuration.
Request
| Attribute | Type | Example Value | Description |
|---|---|---|---|
Application |
Header Application Key | "f3a90488ffee32c3acb6fcd0ca417cf6" | Specific Management Center application key provided by PAR Menu |
X-API-Authorization |
Header | "32c3acb6fcd0ca417cf6f3a90488ffee" | Basic Authorization header is based on the previously received client_id and client_secret and is generated as follows : base_64_encode(client_id:client_secret) |
{
"method": "post",
"url": "https://api-public-playground.menu.app/api/oauth/tokens",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": 4.44.0,
"X-Role-ID": ""
},
"body":{
"grant_type": "client_credentials",
"scope": "order"
}
}
Response
{
"status": "OK",
"code": 200,
"data": {
"oauth_token": {
"access_token": "d4c129d3f4560c2beaa3a1a3b15bb771a7038a4bbb680a3912c9ea284d07b291",
"token_type": "bearer",
"scope": "webhooks-management",
"expires_in": 86399
}
}
}
| Attribute | Type | Example Value | Description |
|---|---|---|---|
oauth_token.access_token |
string | "f3a90488ffee32c3acb6fcd0ca417cf6" |
Access token for the future creation and editing of the webhooks configurations. This token should be used as Bearer token in the next calls. |
oauth_token.expires_in |
int | "86399" | Token expiration time in seconds |
Get webhook configurations
Once the access_token is obtained it is possible to check the current webhook configuration. By calling [/api/webhook-configs]
the collection of the webhook configurations can be obtained:
| Attribute | Type | Example Value | Description |
|---|---|---|---|
Authorization |
Header | "Bearer 0ca417cf6f3a90488ffee32c3acb6fcd" |
Bearer token, should be the access_token received in the previous call |
{
"method": "get",
"url": "https://api-public-playground.menu.app/api/webhook-configs",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ",
"Api-Version": 4.38.0,
"X-Role-ID": "",
"X-Ordering-API": true
}
}
Response
{
"status": "OK",
"code": 200,
"data": {
"webhook-configs": [
{
"id": "b9573e87-747f-411b-b227-96cf5971ecaf",
"signing_secret": "mySup3rSecR3tSignKey123!",
"url": "http://baseurl.service.menu.app:8084",
"created_at": "2023-07-26T12:29:04Z",
"updated_at": "2023-07-26T12:29:04Z"
}
]
}
}
| Attribute | Type | Example Value | Description |
|---|---|---|---|
webhook-configs[i].signing_secret |
string | "f3a90488ffee32c3acb6fcd0ca417cf6" |
Signing secret used to sign webhook requests to verify the requests are sent by PAR Menu |
webhook-configs[i].url |
string | "https://baseurl.com" |
Client Application base URL |
webhook-configs[i].created_at |
string | "2023-07-26T12:29:04Z" |
Configuration creation date |
webhook-configs[i].updated_at |
string | "2023-07-26T12:29:04Z" |
Last configuration update timestamp |
Register for order status updates
To register a new webhook configuration the POST /api/webhook-configs should be called, specifying the base url and signing secret.
| Attribute | Type | Example Value | Description |
|---|---|---|---|
Authorization |
Header | "Bearer 0ca417cf6f3a90488ffee32c3acb6fcd" |
Bearer token, should be the access_token received in the previous call |
{
"method": "post",
"url": "https://api-public-playground.menu.app/api/webhook-configs",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ",
"Api-Version": 4.38.0,
"X-Role-ID": "",
"X-Ordering-API": true
},
"body":{
"url": "http://dispatch-service.menu.app:8084",
"signing_secret": "mySup3rSecR3tSignKey123!"
}
}
Response
{
"status": "OK",
"code": 200,
"data": {
"webhook-configs": [
{
"id": "b9573e87-747f-411b-b227-96cf5971ecaf",
"signing_secret": "mySup3rSecR3tSignKey123!",
"url": "http://baseurl.service.menu.app:8084",
"created_at": "2023-07-26T12:29:04Z",
"updated_at": "2023-07-26T12:29:04Z"
}
]
}
}
| Attribute | Type | Example Value | Description |
|---|---|---|---|
webhook-configs[i].signing_secret |
string | "f3a90488ffee32c3acb6fcd0ca417cf6" |
Signing secret used to sign webhook requests to verify the requests are sent by PAR Menu |
webhook-configs[i].url |
string | "https://baseurl.com" |
Client Application base URL |
webhook-configs[i].created_at |
string | "2023-07-26T12:29:04Z" |
Configuration creation date |
webhook-configs[i].updated_at |
string | "2023-07-26T12:29:04Z" |
Last configuration update timestamp |
Editting the Webhook Configurations
In case the webhook configurations are to be changed, the PATCH /api/webhook-configs/{{configuration_uuid}} can be used to update some specific fields of the webhook configuration:
{
"method": "patch",
"url": "https://api-public-playground.menu.app/api/webhook-configs/{{congifuration_uuid}}",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ",
"Api-Version": 4.38.0,
"X-Role-ID": "",
"X-Ordering-API": true
},
"body":{
"url": "http://dispatch-service.menu.app:8084",
"signing_secret": "mySup3rSecR3tSignKey123!"
}
}
The configuration can also be removed by calling DELETE /api/webhook-configs/{{configuration_uuid}}
{
"method": "patch",
"url": "https://api-public-playground.menu.app/api/webhook-configs/{{congifuration_uuid}}",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ",
"Api-Version": 4.38.0,
"X-Role-ID": "",
"X-Ordering-API": true
}
}
Receiving Webhook Order Status Updates
Each order status update is transmitted via a simplified payload, ensuring efficient data transfer. Notably, retry mechanisms are strategically implemented, primarily for handling final statuses, to guarantee the delivery and reliability of critical information.
Webhook Payload
{
"uuid": "3c9d74fd-c862-4387-b056-1d1d29b1e41a",
"type": "order.status_update",
"sent_at": "2023-07-20 15:36",
"created_at": "2023-07-20 15:02",
"data": {
"uuid": "b6a7f4de-2423-4983-8bf1-1a14b0179f63",
"state": "Final",
"code": "HA3S6",
"created_at": "2023-07-20 14:55",
"updated_at": "2023-07-20 15:35"
}
}
| Attribute | Type | Example Value | Description |
|---|---|---|---|
data.uuid |
string | "b6a7f4de-2423-4983-8bf1-1a14b0179f63" |
Order UUID |
data.state |
string | "Final" |
New order status (See Order Statuses for more information) |
data.code |
string | "HA3S6" |
Order code used in CMS and Management Center |
data.created_at |
string | "2023-07-20 14:55" |
Order creation date |
data.updated_at |
string | "2023-07-20 14:55" |
Last order update timestamp |