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: