Wolt Drive API webhook service

Webhooks provide a mechanism for the merchant to receive information related to e.g. status changes of a single delivery. The Wolt Drive API contains CRUD endpoints for managing the webhooks.

The webhooks operate in the merchant level: the webhook events related to all the venues of the merchant will be sent to the same endpoint. I.e. the merchant needs to configure only a single webhook in order to receive all the events related to all the stores.

The merchant system will need to provide a callback_url and client_secret for each webhook it registers.

Each event is encoded into a JSON Web Token (JWT) and will be sent in the format: "token": "<payload as HS256 encoded JWT>". After receiving and decoding the payload, the system can validate the event origin by verifying the secret (signature) which it provided while registering the webhook. Signature is not base64 encoded.

The following sequence diagram visualizes the webhook related operations.

Endpoints for managing webhooks

All the requests must contain Authorization: Bearer <token> header. This token is often referred as Merchant Key. Staging token will be provided by Wolt when you start the integration development and the production token when you successfully complete the testing phase. Only one token per merchant is needed.

Create a webhook

Create a webhook to be used to send events

POST /v1/merchants/{merchant_id}/webhooks

POST /v1/merchants/{merchant_id}/webhooks

{
  "callback_config": {
    "exponential_retry_backoff": {
      "exponent_base": 5,
      "max_retry_count": 3
    }
  },
  "callback_url": "string",
  "client_secret": "string",
  "disabled": false
}

Create webhook response

201 Created

{
  "callback_config": {
    "exponential_retry_backoff": {
      "exponent_base": 0,
      "max_retry_count": 0
    }
  },
  "callback_url": "string",
  "created_at": "string",
  "disabled": true,
  "id": "string",
  "modified_at": "string",
  "subscribed_events": [
    "string"
  ]
}

Get a list of webhooks

Get a list of all webhook configured under the merchant ID.

GET /v1/merchants/{merchant_id}/webhooks

GET /v1/merchants/{merchant_id}/webhooks

curl {{host}}/v1/merchants/{merchant_id}/webhooks \
  -H "Authorization: Bearer (token)"

List all webhooks response

200 Ok
[
  {
    "callback_config": {
      "exponential_retry_backoff": {
        "exponent_base": 0,
        "max_retry_count": 0
      }
    },
    "callback_url": "string",
    "created_at": "string",
    "disabled": true,
    "id": "string",
    "modified_at": "string",
    "subscribed_events": [
      "string"
    ]
  }
]

Get a single webhook

GET /v1/merchants/{merchant_id}/webhooks/{webhook_id}

GET /v1/merchants/{merchant_id}/webhooks/{webhook_id}

curl {{host}}/v1/merchants/{merchant_id}/webhooks/{webhook_id} \
  -H "Authorization: Bearer (token)"

Get a single webhook response

200 Ok
  {
    "callback_config": {
      "exponential_retry_backoff": {
        "exponent_base": 0,
        "max_retry_count": 0
      }
    },
    "callback_url": "string",
    "created_at": "string",
    "disabled": true,
    "id": "string",
    "modified_at": "string",
    "subscribed_events": [
      "string"
    ]
  }

Update a webhook

Change the webhook configuration and the subscribed events.

PATCH /v1/merchants/{merchant_id}/webhooks/{webhook_id}

PATCH /v1/merchants/{merchant_id}/webhooks/{webhook_id}

{
  "callback_config": {
    "exponential_retry_backoff": {
      "exponent_base": 0,
      "max_retry_count": 0
    }
  },
  "callback_url": "string",
  "client_secret": "string",
  "disabled": false,
  "subscribed_events": ["order.received"]
}

Delete a webhook

DELETE /v1/merchants/{merchant_id}/webhooks/{webhook_id}

DELETE /v1/merchants/{merchant_id}/webhooks/{webhook_id}

curl -X DELETE {{host}}/v1/merchants/{merchant_id}/webhooks/{webhook_id} \
  -H "Authorization: Bearer (token)"

204 No content

Webhook order events

Webhook order event types

Order event payload

{
  "dispatched_at": "2023-01-01T00:00:00.000Z",
  "type": "order.received",
  "details": {
    "id": "string",
    "venue_id": "string",
    "wolt_order_reference_id": "string",
    "tracking_reference": "string",
    "merchant_order_reference_id": "string",
    "order_number": "string",
    "price": {
      "amount": 0,
      "currency": "string"
    },
    "pickup": {
      "eta": "2023-01-01T00:00:00.000Z"
    },
    "dropoff": {
      "eta": {
        "min": "2023-01-01T00:00:00.000Z",
        "max": "2023-01-01T00:00:00.000Z"
      },
      "completed_at": "2023-01-01T00:00:00.000Z"
    },
    "courier": {
      "id": 0,
      "vehicle_type": "car"
    },
    "parcels": [
      {
        "description": "string",
        "identifier": "string"
      }
    ],
    "purchase_rejected_reason": "GENERIC_VENUE_REQUESTED"
  }
}

Location updated

This event type order.location_updated is optional. When enabled, expect a heavy event load and consider creating a separate configuration for the event. Location refers to the current location of assigned courier partner.

{
  "dispatched_at": "2023-01-01T00:00:00.000Z",
  "type": "order.location_updated",
  "details": {
    "id": "string",
    "wolt_order_reference_id": "string",
    "merchant_order_reference_id": "string",
    "order_number": "string",
    "tracking_id": "string",
    "courier_location": {
      "lat": 0.0,
      "lon": 0.0
    }
  }
}

Handshake delivery

This event type order.handshake_delivery is only sent when the delivery has delivery handshake verification enabled.

{
  "dispatched_at": "2023-01-01T00:00:00.000Z",
  "type": "order.handshake_delivery",
  "details": {
    "id": "string",
    "wolt_order_reference_id": "string",
    "merchant_order_reference_id": null,
    "order_number": "string",
    "pin_code": "string"
  }
}