Consumer reviews integration

Use case

Wolt consumers are prompted with a request to review their order experience after each completed order. This is optional, so not every order is reviewed. The consumer review consists of two phases - Goods & Delivery. The reviews shared with the merchants are the ones relevant for their model - only merchants who self-delivered a purchase, will be shared with the purchase’s “Delivery” rating.

This integration is done by accepting a notification to your webhook URL. This notification is triggered by an opt-in configuration for each venue (store). Contact your account manager to enable these.

Requirements

Webhook server

You must have a webhook server to be able to receive order status webhook notifications. These notifications will inform you of the status of the order.

For Wolt to know where to send the status notifications we need to know the URL of your webhook server. Inform your Wolt account manager the URL of your webhook server.

Webhook server security

The partner must provide a client secret that must be different from the API key, 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

Both the API key and client secret should be stored and provided to the application securely. Knowledge of either value may allow an attacker to act as the partner. The design should allow either value to be changed easily in the event they would leak. In particular, the values should not be stored in source code or plaintext configuration files.

Wolt signature example

  • 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.

POST /webhook
{
  "id": "6638a4b2aba7864c06699a7b",
  "type": "order_review.notification",
  "order": {
    "id": "90f5be47fc97e11107f8a480",
    "venue_id": "9a5c7e3102fe6a000c4b562b",
    "resource_url": "https://pos-integration-service.wolt.com/orders/90f5be47fc97e11107f8a480"
  },
  "review": {
    "goods_review": {
      "rating": 3,
      "comment": "Nice food!",
      "attributions": ["PACKAGING", "FLAVOUR", "PORTION_SIZE"],
      "missing_items": [
        { "pos_id": "VEGANBURG", "sku": "ABC-12345-BR", "gtin": "012345678905" },
        { "pos_id": "CHICKBURG", "sku": "XYZ-12345-BR", "gtin": "012345678906" }
      ]
    },
    "delivery_review": {
      "rating": 1,
      "comment": "I was expecting a much better delivery.",
      "attributions": ["ESTIMATE"],
      "missing_items": [
        { "pos_id": "VEGANBURG", "sku": "ABC-12345-BR", "gtin": "012345678905" },
        { "pos_id": "CHICKBURG", "sku": "XYZ-12345-BR", "gtin": "012345678906" }
      ]
    }
  },
  "created_at": "2024-05-06T09:36:50.979947759Z"
}

Wolt always sends the JSON body in compact format, as in the curl request. The body received from the webhook is the payload Wolt uses to generate the signature.

Integration workflow

1. Order is completed

Delivery orders are completed when a courier has delivered those to the consumer at the dropoff address. Takeaway orders are completed when the merchant is marking those as ‘delivered’ to the user (either manually using the Merchant App, or using the dedicated endpoint)

2. Order is reviewed by consumer

Users are prompted to review the purchase. In case they choose to review, they are presented with the option to rate (1-5, displayed as emojis) and add “tags” to say what went well, or what could be improved. Users can also add a free-text comment. This appears once for the delivery rating, and once for the goods rating.

3. Rating notification is sent

The notification is sent to the webhook URL, according to all conditions mentioned above.

Notification body fields

Order review notification payload example
{
  "id": "6638a4b2aba7864c06699a7b",
  "type": "order_review.notification",
  "order": {
    "id": "90f5be47fc97e11107f8a480",
    "venue_id": "9a5c7e3102fe6a000c4b562b",
    "resource_url": "https://pos-integration-service.wolt.com/orders/90f5be47fc97e11107f8a480"
  },
  "review": {
    "goods_review": {
      "rating": 3,
      "comment": "Nice food!",
      "attributions": ["PACKAGING", "FLAVOUR", "PORTION_SIZE"],
      "missing_items": [
        { "pos_id": "VEGANBURG", "sku": "ABC-12345-BR", "gtin": "012345678905" },
        { "pos_id": "CHICKBURG", "sku": "XYZ-12345-BR", "gtin": "012345678906" }
      ]
    },
    "delivery_review": {
      "rating": 1,
      "comment": "I was expecting a much better delivery.",
      "attributions": ["ESTIMATE"],
      "missing_items": [
        { "pos_id": "VEGANBURG", "sku": "ABC-12345-BR", "gtin": "012345678905" },
        { "pos_id": "CHICKBURG", "sku": "XYZ-12345-BR", "gtin": "012345678906" }
      ]
    }
  },
  "created_at": "2024-05-06T09:36:50.979947759Z"
}

Body of the notification contains all of the review data. That is separated between two parts - “goods_review” for the content of the purchase (items, food, TA experience) and “delivery_review” for the delivery of the purchase (courier behaviour, estimate etc) - only appears when the merchant has fulfilled this delivery by themselves.

Goods review

  1. Rating (1-5); 1 being the lowest

  2. Comment - free text comment optionally left by the user

  3. Attributions - a set of one (or more) optional “tags” chosen by the user; these tags, combined with a “negative” rating (1-3), are an indication for an issue the customer experienced. Combined with a “positive” rating (4-5), these indicate a good experience:

    • COMMENT - a free comment was added
    • MISSING ITEM - there was one (or more) missing item(s)
    • APPEARANCE, FLAVOUR, FOOD, PACKAGING, PORTION_SIZE, TEXTURE, QUALITY, VALUE_FOR_MONEY - the food’s (or goods’) appearance was noted by the user.
    • PRODUCT_DAMAGED - there was one or more item(s) delivered in a damaged state, according to the user’s review.
    • ATMOSPHERE, HAD_TO_QUEUE, VENUE, STAFF, EXPERIENCE - this attributions can only be selected when reviewing a takeaway order; these refer to the experience of the user getting to the store, waiting and picking up (directions, staff, store etc)

  4. Missing items - a set of one (or more) identifiers of items, which according to the user’s review, weren’t delivered.

Delivery review

  1. Rating (1-5); 1 being the lowest

  2. Comment - free text comment optionally left by the user

  3. Attributions - a set of one (or more) optional “tags” chosen by the user; these tags, combined with a “negative” rating (1-3), are an indication for an issue the customer experienced. Combined with a “positive” rating (4-5), these indicate a good experience:

    • COLD_FOOD - food arrived cold to the user.
    • COMMENT - a free comment was added
    • COURIER - the user noted the courier’s behaviour or approach as a key reason for their rating
    • DELIVERY_INSTRUCTIONS - the instructions left by the user (eg “don’t ring the doorbell”) were a key reason for their rating
    • DELIVERY_TIME - the user noted the delivery time as a key reason for their rating
    • ESTIMATE - the user noted the delivery time estimate (what was promised ahead of purchasing) as a key reason for their rating

  4. Missing items - a set of one (or more) identifiers of items, which according to the user’s review, weren’t delivered.