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. 

Order related webhook notifications

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.

Courier Events Notifications

Courier Nearby / Geofencing

Receive a notification when the courier is closing in on your venue; use it as a trigger to start food preparation.

If a venue's preparation time is 10 minutes then courier arrival webhook notification gets send 10 minutes before the courier's arrival at the venue. Courier's arrival to the venue is calculated based on the courier's GPS location. This is also known as geofencing.

{
"id": "6278d17060f7596392151fe2",
"type": "courier.notification",
"order": {
"id": "6278d13b14cfacea171f08fd",
"venue_id": "624435265ea2063dfd7681ed",
"resource_url": "https://pos-integration-service.development.dev.woltapi.com/orders/6
},
"courier_details": {
"courier_pickup_eta": "2026-05-09T08:33:03Z"
},
"created_at": "2026-05-09T08:31:44.285646Z"
}

Order Picked Up by Courier

When an order is picked up by our courier, we send pickup completed webhook notification. This will let you know that the order was picked up by the courier in the store.

{
"id": "6630d3034b4f2f54c43c727a",
"type": "pickup_completed.notification",
"order": {
"id": "90f5be47fc97e11107f8a480",
"venue_id": "9a5c7e3102fe6a000c4b562b",
"resource_url": "https://pos-integration-service.wolt.com/orders/90f5be47fc97e11107f8
},
"details": {
"is_pickup_completed": true
},
"created_at": "2021-07-19T18:20:12.378509Z"
}

Venue Events Notifications

Receive real-time notifications when operational events occur at your venues. Ask your Wolt contact to enable these for you.

Example Webhook JSON

This is the basic payload format shared by all venue notifications. Events with richer context have additional fields in details as shown in the sections below.

{
  "event_type": "VENUE_OFFLINE_ALERT_TRIGGERED",
  "venue_id": "507f191e810c19729de860ea",
  "external_venue_id": "STORE-001",
  "detected_at": "2026-02-13T14:30:00Z",
  "details": {}
}

REJECTION_ALERT_TRIGGERED / REJECTION_ALERT_RECOVERED

Sent when a venue reaches the consecutive rejection threshold (triggered) or processes a successful order after an alert (recovered). The details object is empty for both events

{
  "event_type": "REJECTION_ALERT_RECOVERED",
  "venue_id": "507f191e810c19729de860ea",
  "external_venue_id": "STORE-001",
  "detected_at": "2026-02-13T15:10:00Z",
  "details": {}
}

VENUE_OFFLINE_ALERT_TRIGGERED

{
  "event_type": "VENUE_OFFLINE_ALERT_TRIGGERED",
  "venue_id": "507f191e810c19729de860ea",
  "external_venue_id": "STORE-001",
  "detected_at": "2026-02-13T14:30:00Z",
  "details": {
    "offline_since": "2026-02-13T14:25:00Z",
    "expected_open_until": "2026-02-13T22:00:00Z",
    "offline_period_ending": "2026-02-13T16:00:00Z",
    "change_context": {
      "change_source": "merchant-app",
      "change_reason": "closing early",
      "changed_by": "user@example.com"
    }
  }
}

VENUE_OFFLINE_ALERT_RECOVERED

Only sent if a VENUE_OFFLINE_ALERT_TRIGGERED was previously delivered for that venue.

{
  "event_type": "VENUE_OFFLINE_ALERT_RECOVERED",
  "venue_id": "507f191e810c19729de860ea",
  "external_venue_id": "STORE-001",
  "detected_at": "2026-02-13T14:35:00Z",
  "details": {
    "back_online_since": "2026-02-13T14:34:00Z",
    "change_context": {
      "change_source": "merchant-app",
      "change_reason": "reopening after break",
      "changed_by": "user@example.com"
    }
  }
}

OPENING_HOURS_UPDATED

{
  "event_type": "OPENING_HOURS_UPDATED",
  "venue_id": "507f191e810c19729de860ea",
  "external_venue_id": "STORE-001",
  "detected_at": "2026-02-13T09:00:00Z",
  "details": {
    "changed_fields": ["REGULAR_HOURS", "EXCEPTIONAL_HOURS"],
    "previous": {
      "regular_hours": {
        "monday": [{ "open": "10:00", "close": "22:00" }]
      },
      "exceptional_hours": null,
      "offline_period": null
    },
    "current": {
      "regular_hours": {
        "monday": [{ "open": "09:00", "close": "23:00" }]
      },
      "exceptional_hours": [
        {
          "date": "2026-02-20",
          "hours": [{ "open": "10:00", "close": "18:00" }]
        }
      ],
      "offline_period": null
    },
    "change_context": {
      "change_source": "merchant-admin",
      "changed_by": "admin@merchant.com"
    }
  }
}

Order Reviews

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.

{
  "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"
}

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.

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

• 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 5 seconds, followed by two additional retries at 5-second intervals.