Webhook

Introduction

You will need to have a webhook server to be able to receive webhook notifications. These notifications will inform you of the status changes for each order, additional information about courier statuses and provide ratings of consumers on a purchase made.

Types of Webhook notifications

Status Type	Description
`"CREATED"`	Sent for all new orders which the merchant is receiving on the Wolt marketplace.
`"PRODUCTION"`	Sent once the order has been accepted or confirmed* by the venue staff, either automatically or manually. *pre-orders should be confirmed upon creation, Wolt will move them automatically in `"PRODUCTION`" status when it's time to start the food preparation or order collection.
`"READY"`	Sent once the merchant has completed the preparation or collection of the order.
`"CANCELED"`	Sent once the order has been “rejected”, either by the merchant, the customer or Wolt Support.
`"COURIER ARRIVAL"` *optional	Sent X* min before the courier's arrival at the merchant's location. *X is configurable per location.
`"PICK-UP-COMPLETED"` *optional	Sent once the courier has completed the pick-up at the merchant's location.
`"DELIVERED"`	Sent once the order is delivered to the customer.
`"REVIEW"` *optional	Sent once a consumer has provided a review or rating of their order.

Example Webhook JSON

{
  "id": "90f5c25cbbfb3d131a46e643",
  "type": "order.notification",
  "order": {
    "id": "90f5be47fc97e11107f8a480",
    "venue_id": "9a5c7e3102fe6a000c4b562b",
    "status": "PRODUCTION",
    "resource_url": "https://pos-integration-service.wolt.com/orders/90f5be47fc97e11107f8a480"
  },
  "created_at": "2021-07-19T18:20:12.378509Z"
}

Making use of the notification

Your system can fetch the order payload by using the resource_url field. You can also hardcode the base URL and use the order.id field's value to pull order details. Moreover, some notifications can be used to decide the order parsing moment for the POS or using it to submit reminder on pending order to venue staff.

Two Types of order payload

The resource URL used in the notification body allows to poll an outdated order payload. As Wolt runs two versions of the order payload, please make sure you develop towards /v2/orders/{orderId}

Webhook server security

Please provide a client secret that is cryptographically random and at least 128 bits in length. This will be used to sign the webhook body using HMAC-SHA256.

Wolt signs the request by generating a signature from the request body, using the client secret, and sending it alongside the request.

Wolt signature specification

Notifications are signed with HMAC-SHA256.
String format for the signature is HEX.
The signature is placed to the WOLT-SIGNATURE HTTP request header.
The secret key for generating the signature from the request body is the client secret

Wolt signature example --- would remove

Client secret: example-hmac-sha256-wolt

To generate the signature of the body, use HMAC-SHA256 with the client secret provided to Wolt. Generate it from the request body (i.e. the notification), and compare it to the value in the wolt-signature header.

Expected response

We require a 200 response to acknowledge our notification was received correctly. Otherwise, the notification will fall back into the retry logic.

Retry logic

We will submit the first retry after 10 milliseconds, followed by two additional retries each after 10 milliseconds.