Webhooks: Order Status Updates
After an order is placed you need to know when its status changes so you can tell the customer. Rather than polling, register a webhook: we POST to a URL you own every time the status moves, and again when a payment is refunded or voided.
This guide covers registering your endpoint, what we send to it, and how to verify that a call came from us.
Before proceeding, you should have implemented:
Register for webhook order status updates
Webhook configuration is a server-to-server API. It needs an OAuth client token rather than a customer token, and every webhook we send is signed with the signing_secret you register, so you can check it came from us.
Your Integration Manager issues the client_id and client_secret for the OAuth client.
Generate an access token
Exchange the client credentials for a token at POST /oauth/tokens, using HTTP Basic authentication and the client_credentials grant. Ask for the webhooks-management scope; it is also what you get when you send no scope at all.
Request
| Attribute | Type | Example Value | Description |
|---|---|---|---|
Application |
Header | "f3a90488ffee32c3acb6fcd0ca417cf6" |
Application key provided by PAR |
Authorization |
Header | "Basic MGNhNDE3Y2Y2OmYzYTkwNDg4" |
Basic credentials, generated as base_64_encode(client_id:client_secret) |
{
"method": "post",
"url": "https://api-public-demo.menu.app/api/oauth/tokens",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"Api-Version": "<current-release-version>",
"Authorization": "Basic MGNhNDE3Y2Y2OmYzYTkwNDg4",
"Content-Type": "application/x-www-form-urlencoded"
},
"body":{
"grant_type": "client_credentials",
"scope": "webhooks-management"
}
}
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 | "d4c129d3f4560c2beaa3a1a3b15bb771a7038a4bbb680a3912c9ea284d07b291" |
The token for the webhook configuration calls below |
oauth_token.expires_in |
int | 86399 |
Token lifetime in seconds |
Send the token on X-API-Authorization as a Bearer token, together with X-Ordering-API: true. Authorization is reserved for the customer token and is not read here: Basic credentials on Authorization get you the token, then the token goes on X-API-Authorization. See Ordering API Client for the full explanation.
Get webhook configurations
GET /webhook-configs lists the configurations registered for your application:
| Attribute | Type | Example Value | Description |
|---|---|---|---|
X-API-Authorization |
Header | "Bearer d4c129d3f4560c2beaa3a1a3b15bb771a7038a4bbb680a3912c9ea284d07b291" |
The access_token from the previous call |
X-Ordering-API |
Header | true |
Marks the call as an Ordering API request |
{
"method": "get",
"url": "https://api-public-demo.menu.app/api/webhook-configs",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"X-API-Authorization": "Bearer d4c129d3f4560c2beaa3a1a3b15bb771a7038a4bbb680a3912c9ea284d07b291",
"Api-Version": "<current-release-version>",
"X-Ordering-API": true
}
}
Response
{
"status": "OK",
"code": 200,
"data": {
"webhook-configs": [
{
"id": "b9573e87-747f-411b-b227-96cf5971ecaf",
"signing_secret": "mySup3rSecR3tSignKey123!",
"url": "https://example.com/par-ordering/webhooks",
"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 | "mySup3rSecR3tSignKey123!" |
The secret we sign every webhook with, so you can verify the sender |
webhook-configs[i].url |
string | "https://example.com/par-ordering/webhooks" |
The URL we POST each event to |
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
Call POST /webhook-configs with the URL we should post to and the secret we should sign with.
| Attribute | Type | Example Value | Description |
|---|---|---|---|
X-API-Authorization |
Header | "Bearer d4c129d3f4560c2beaa3a1a3b15bb771a7038a4bbb680a3912c9ea284d07b291" |
The access_token from the previous call |
X-Ordering-API |
Header | true |
Marks the call as an Ordering API request |
{
"method": "post",
"url": "https://api-public-demo.menu.app/api/webhook-configs",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"X-API-Authorization": "Bearer d4c129d3f4560c2beaa3a1a3b15bb771a7038a4bbb680a3912c9ea284d07b291",
"Api-Version": "<current-release-version>",
"X-Ordering-API": true,
"Content-Type": "application/json"
},
"body":{
"url": "https://example.com/par-ordering/webhooks",
"signing_secret": "mySup3rSecR3tSignKey123!"
}
}
Response
{
"status": "OK",
"code": 200,
"data": {
"webhook-configs": [
{
"id": "b9573e87-747f-411b-b227-96cf5971ecaf",
"signing_secret": "mySup3rSecR3tSignKey123!",
"url": "https://example.com/par-ordering/webhooks",
"created_at": "2023-07-26T12:29:04Z",
"updated_at": "2023-07-26T12:29:04Z"
}
]
}
}
Editing the webhook configuration
PATCH /webhook-configs/{id} updates the URL, the secret, or both:
{
"method": "patch",
"url": "https://api-public-demo.menu.app/api/webhook-configs/b9573e87-747f-411b-b227-96cf5971ecaf",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"X-API-Authorization": "Bearer d4c129d3f4560c2beaa3a1a3b15bb771a7038a4bbb680a3912c9ea284d07b291",
"Api-Version": "<current-release-version>",
"X-Ordering-API": true,
"Content-Type": "application/json"
},
"body":{
"url": "https://example.com/par-ordering/webhooks-v2",
"signing_secret": "mySup3rSecR3tSignKey123!"
}
}
DELETE /webhook-configs/{id} removes it:
{
"method": "delete",
"url": "https://api-public-demo.menu.app/api/webhook-configs/b9573e87-747f-411b-b227-96cf5971ecaf",
"headers": {
"X-Request-ID": "69da3547-204b-4093-a225-54e084c24215",
"Application": "f3a90488ffee32c3acb6fcd0ca417cf6",
"X-API-Authorization": "Bearer d4c129d3f4560c2beaa3a1a3b15bb771a7038a4bbb680a3912c9ea284d07b291",
"Api-Version": "<current-release-version>",
"X-Ordering-API": true
}
}
Receiving webhook order status updates
We POST one JSON document per event to the URL you registered. The envelope is the same for every event; type tells you which kind it is, and data is the order.
Webhook payload
{
"uuid": "3c9d74fd-c862-4387-b056-1d1d29b1e41a",
"type": "order.status_update",
"sent_at": "2023-07-20 15:36",
"created_at": "2023-07-20 14:55",
"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 |
|---|---|---|---|
uuid |
string | "3c9d74fd-c862-4387-b056-1d1d29b1e41a" |
Unique id of this delivery attempt. A retry carries a new one. |
type |
string | "order.status_update" |
order.status_update, order.payment_status_refund or order.payment_status_voided |
sent_at |
string | "2023-07-20 15:36" |
When we sent this event, in UTC |
created_at |
string | "2023-07-20 14:55" |
The order's creation time, in UTC — the same value as data.created_at |
data.uuid |
string | "b6a7f4de-2423-4983-8bf1-1a14b0179f63" |
Order UUID |
data.state |
string | "Final" |
For order.status_update: the new order status, one of Init, InPreparation, Ready, Final, Canceled or Failed (see Order Statuses). For the payment events: RefundedPartially, RefundedFully or Voided. |
data.code |
string | "HA3S6" |
Order code shown in the Management Center |
data.created_at |
string | "2023-07-20 14:55" |
Order creation date |
data.updated_at |
string | "2023-07-20 15:35" |
Last order update timestamp |
Verifying the sender
Each request carries an Authorization header holding the hex-encoded HMAC-SHA256 of the raw request body, keyed with your signing_secret. Compute the same over the body exactly as received, compare the two in constant time, and reject anything that does not match. Do not parse the body before you have checked it.
Retries
Answer with any 2xx status as soon as you have stored the event; do your own processing afterward. If we do not get a 2xx, events that end an order's life — Final, Canceled, Failed, and the refund and void events — are retried up to 10 times, one minute apart. The other statuses are sent once. Because a retry can arrive after you have already processed the original, treat data.uuid plus data.state as the idempotency key for order statuses — an order passes through each status once. Payment events are different: RefundedPartially can legitimately arrive more than once for the same order, so for refunds and voids compare updated_at too, or reconcile against your own refund records, before you discard a repeat.
What the webhook does not carry
The payload is only those five fields. There is no courier position, no tracking link and no delivery-specific status in it.
For a delivery order handled by PAR Dispatch, read state like this: Ready means a courier has accepted the job and is on the way, and Final means the order was handed to the customer. There is no separate "out for delivery" or "delivered" value.
When you need more than that, go back to the order:
delivery_statuson Get Order follows the courier (Underway,Completed, …) — see Delivery statuses.- The courier's live position and, for providers such as DoorDash Drive, the provider's own tracking page come from Driver Tracking. The walkthrough is in Track the courier.
