Skip to content
Delivr Developers

Set the events you subscribe to

PUT
/v1/merchant/webhook/events
curl --request PUT \
  --url https://driver-staging-api.delivr.no/v1/merchant/webhook/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0' \
  --data '{ "events": [ "order.placed" ] }'

An empty or omitted list subscribes to every event. webhook.test is always delivered.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
required
string format: uuid

A UUID, one header. A retry of the same request (method, path, canonical JSON body) within 24 h gets the first successful reply again (Idempotent-Replayed: true). Another request under the key is 422 idempotency_key_reused; a retry while the first runs is 409 idempotency_key_in_flight. Refused or failed requests free the key.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
events
Array<string>
unique items
Allowed values: order.placed order.scheduled order.searching order.driver_assigned order.picked_up order.delivered order.cancelled order.failed order.held order.ready_at_changed order.ready_overdue order.window_changed order.successor_created order.awaiting_recipient order.fallback_cancelled

Responses

Section titled “Responses”

200

Section titled “200”

The endpoint.

Media typeapplication/json
object
url
required
string format: uri
secretPrefix
required

First characters of the signing secret (whsec_...).

string
previousSecretUntil

A rotated-out secret also signs until then.

string format: date-time
events

Absent - every event.

Array<string>
Allowed values: order.placed order.scheduled order.searching order.driver_assigned order.picked_up order.delivered order.cancelled order.failed order.held order.ready_at_changed order.ready_overdue order.window_changed order.successor_created order.awaiting_recipient order.fallback_cancelled
updatedAt
required
string format: date-time

Example 

{
  "events": [
    "order.placed"
  ]
}

Headers

Section titled “Headers”
X-Request-Id
string

The request’s id (yours if you sent a valid one, up to 64 of A-Za-z0-9._-). Quote it to support.

400

Section titled “400”

malformed_json, idempotency_key_required.

Media typeapplication/json
object
error
required
object
code
required

Status per code: 400 malformed_json, idempotency_key_required; 401 unauthenticated; 403 merchant_suspended, insufficient_scope; 404 not_found, quote_not_found; 405 method_not_allowed; 409 conflict, cancellation_not_allowed, idempotency_key_in_flight, price_changed, option_unavailable, fee_changed, quote_already_used, external_ref_taken, window_full, order_ended; 422 invalid_request, idempotency_key_reused, no_delivery_options, manual_quote_required, invalid_address; 429 rate_limited; 500 internal; 503 unavailable.

string
Allowed values: invalid_request malformed_json not_found method_not_allowed unauthenticated merchant_suspended insufficient_scope conflict cancellation_not_allowed idempotency_key_required idempotency_key_reused idempotency_key_in_flight unavailable rate_limited quote_not_found no_delivery_options manual_quote_required invalid_address price_changed option_unavailable fee_changed quote_already_used external_ref_taken window_full order_ended internal
message
required

Human-readable; may change. Branch on code.

string
param

The request field at fault, e.g. delivery.address (an unknown field: its name).

string
requestId
string
details
One of:
object
quotedAmountMinor
required
integer
option
required
object
type
required
string
Allowed values: on_demand window
key
required

Stable key to book (on_demand or window:<start>/<end> in the market’s zone). The same delivery quoted again lists the same keys.

string
eta

On demand. Arrival band.

object
from
required
string format: date-time
to
required
string format: date-time
window

Window option.

object
start
required
string format: date-time
end
required
string format: date-time
cutoffAt

Window option. Book and cancel free before it.

string format: date-time
price
required
object
amountMinor
required

VAT included.

integer
vatMinor
integer
exVatMinor
integer
currency
required
string
supply

On demand only. HINT for the seller, never a promise: drivers near the store when quoted and when the first-ranked could reach it. Do not show a driver count to shoppers.

object
nearbyDrivers
required
integer
pickupEta
required
object
from
required
string format: date-time
to
required
string format: date-time

Example 

{
  "error": {
    "code": "invalid_request",
    "details": {
      "option": {
        "type": "on_demand",
        "key": "on_demand",
        "price": {
          "currency": "NOK"
        }
      }
    }
  }
}

401

Section titled “401”

unauthenticated: missing, unknown or revoked key.

Media typeapplication/json
object
error
required
object
code
required

Status per code: 400 malformed_json, idempotency_key_required; 401 unauthenticated; 403 merchant_suspended, insufficient_scope; 404 not_found, quote_not_found; 405 method_not_allowed; 409 conflict, cancellation_not_allowed, idempotency_key_in_flight, price_changed, option_unavailable, fee_changed, quote_already_used, external_ref_taken, window_full, order_ended; 422 invalid_request, idempotency_key_reused, no_delivery_options, manual_quote_required, invalid_address; 429 rate_limited; 500 internal; 503 unavailable.

string
Allowed values: invalid_request malformed_json not_found method_not_allowed unauthenticated merchant_suspended insufficient_scope conflict cancellation_not_allowed idempotency_key_required idempotency_key_reused idempotency_key_in_flight unavailable rate_limited quote_not_found no_delivery_options manual_quote_required invalid_address price_changed option_unavailable fee_changed quote_already_used external_ref_taken window_full order_ended internal
message
required

Human-readable; may change. Branch on code.

string
param

The request field at fault, e.g. delivery.address (an unknown field: its name).

string
requestId
string
details
One of:
object
quotedAmountMinor
required
integer
option
required
object
type
required
string
Allowed values: on_demand window
key
required

Stable key to book (on_demand or window:<start>/<end> in the market’s zone). The same delivery quoted again lists the same keys.

string
eta

On demand. Arrival band.

object
from
required
string format: date-time
to
required
string format: date-time
window

Window option.

object
start
required
string format: date-time
end
required
string format: date-time
cutoffAt

Window option. Book and cancel free before it.

string format: date-time
price
required
object
amountMinor
required

VAT included.

integer
vatMinor
integer
exVatMinor
integer
currency
required
string
supply

On demand only. HINT for the seller, never a promise: drivers near the store when quoted and when the first-ranked could reach it. Do not show a driver count to shoppers.

object
nearbyDrivers
required
integer
pickupEta
required
object
from
required
string format: date-time
to
required
string format: date-time

Example 

{
  "error": {
    "code": "invalid_request",
    "details": {
      "option": {
        "type": "on_demand",
        "key": "on_demand",
        "price": {
          "currency": "NOK"
        }
      }
    }
  }
}

403

Section titled “403”

merchant_suspended, insufficient_scope.

Media typeapplication/json
object
error
required
object
code
required

Status per code: 400 malformed_json, idempotency_key_required; 401 unauthenticated; 403 merchant_suspended, insufficient_scope; 404 not_found, quote_not_found; 405 method_not_allowed; 409 conflict, cancellation_not_allowed, idempotency_key_in_flight, price_changed, option_unavailable, fee_changed, quote_already_used, external_ref_taken, window_full, order_ended; 422 invalid_request, idempotency_key_reused, no_delivery_options, manual_quote_required, invalid_address; 429 rate_limited; 500 internal; 503 unavailable.

string
Allowed values: invalid_request malformed_json not_found method_not_allowed unauthenticated merchant_suspended insufficient_scope conflict cancellation_not_allowed idempotency_key_required idempotency_key_reused idempotency_key_in_flight unavailable rate_limited quote_not_found no_delivery_options manual_quote_required invalid_address price_changed option_unavailable fee_changed quote_already_used external_ref_taken window_full order_ended internal
message
required

Human-readable; may change. Branch on code.

string
param

The request field at fault, e.g. delivery.address (an unknown field: its name).

string
requestId
string
details
One of:
object
quotedAmountMinor
required
integer
option
required
object
type
required
string
Allowed values: on_demand window
key
required

Stable key to book (on_demand or window:<start>/<end> in the market’s zone). The same delivery quoted again lists the same keys.

string
eta

On demand. Arrival band.

object
from
required
string format: date-time
to
required
string format: date-time
window

Window option.

object
start
required
string format: date-time
end
required
string format: date-time
cutoffAt

Window option. Book and cancel free before it.

string format: date-time
price
required
object
amountMinor
required

VAT included.

integer
vatMinor
integer
exVatMinor
integer
currency
required
string
supply

On demand only. HINT for the seller, never a promise: drivers near the store when quoted and when the first-ranked could reach it. Do not show a driver count to shoppers.

object
nearbyDrivers
required
integer
pickupEta
required
object
from
required
string format: date-time
to
required
string format: date-time

Example 

{
  "error": {
    "code": "invalid_request",
    "details": {
      "option": {
        "type": "on_demand",
        "key": "on_demand",
        "price": {
          "currency": "NOK"
        }
      }
    }
  }
}

409

Section titled “409”

conflict, cancellation_not_allowed, idempotency_key_in_flight, price_changed, option_unavailable, window_full, fee_changed, quote_already_used, external_ref_taken, order_ended. See details for what to do.

Media typeapplication/json
object
error
required
object
code
required

Status per code: 400 malformed_json, idempotency_key_required; 401 unauthenticated; 403 merchant_suspended, insufficient_scope; 404 not_found, quote_not_found; 405 method_not_allowed; 409 conflict, cancellation_not_allowed, idempotency_key_in_flight, price_changed, option_unavailable, fee_changed, quote_already_used, external_ref_taken, window_full, order_ended; 422 invalid_request, idempotency_key_reused, no_delivery_options, manual_quote_required, invalid_address; 429 rate_limited; 500 internal; 503 unavailable.

string
Allowed values: invalid_request malformed_json not_found method_not_allowed unauthenticated merchant_suspended insufficient_scope conflict cancellation_not_allowed idempotency_key_required idempotency_key_reused idempotency_key_in_flight unavailable rate_limited quote_not_found no_delivery_options manual_quote_required invalid_address price_changed option_unavailable fee_changed quote_already_used external_ref_taken window_full order_ended internal
message
required

Human-readable; may change. Branch on code.

string
param

The request field at fault, e.g. delivery.address (an unknown field: its name).

string
requestId
string
details
One of:
object
quotedAmountMinor
required
integer
option
required
object
type
required
string
Allowed values: on_demand window
key
required

Stable key to book (on_demand or window:<start>/<end> in the market’s zone). The same delivery quoted again lists the same keys.

string
eta

On demand. Arrival band.

object
from
required
string format: date-time
to
required
string format: date-time
window

Window option.

object
start
required
string format: date-time
end
required
string format: date-time
cutoffAt

Window option. Book and cancel free before it.

string format: date-time
price
required
object
amountMinor
required

VAT included.

integer
vatMinor
integer
exVatMinor
integer
currency
required
string
supply

On demand only. HINT for the seller, never a promise: drivers near the store when quoted and when the first-ranked could reach it. Do not show a driver count to shoppers.

object
nearbyDrivers
required
integer
pickupEta
required
object
from
required
string format: date-time
to
required
string format: date-time

Example 

{
  "error": {
    "code": "invalid_request",
    "details": {
      "option": {
        "type": "on_demand",
        "key": "on_demand",
        "price": {
          "currency": "NOK"
        }
      }
    }
  }
}

422

Section titled “422”

invalid_request (with param), idempotency_key_reused, no_delivery_options, manual_quote_required, invalid_address.

Media typeapplication/json
object
error
required
object
code
required

Status per code: 400 malformed_json, idempotency_key_required; 401 unauthenticated; 403 merchant_suspended, insufficient_scope; 404 not_found, quote_not_found; 405 method_not_allowed; 409 conflict, cancellation_not_allowed, idempotency_key_in_flight, price_changed, option_unavailable, fee_changed, quote_already_used, external_ref_taken, window_full, order_ended; 422 invalid_request, idempotency_key_reused, no_delivery_options, manual_quote_required, invalid_address; 429 rate_limited; 500 internal; 503 unavailable.

string
Allowed values: invalid_request malformed_json not_found method_not_allowed unauthenticated merchant_suspended insufficient_scope conflict cancellation_not_allowed idempotency_key_required idempotency_key_reused idempotency_key_in_flight unavailable rate_limited quote_not_found no_delivery_options manual_quote_required invalid_address price_changed option_unavailable fee_changed quote_already_used external_ref_taken window_full order_ended internal
message
required

Human-readable; may change. Branch on code.

string
param

The request field at fault, e.g. delivery.address (an unknown field: its name).

string
requestId
string
details
One of:
object
quotedAmountMinor
required
integer
option
required
object
type
required
string
Allowed values: on_demand window
key
required

Stable key to book (on_demand or window:<start>/<end> in the market’s zone). The same delivery quoted again lists the same keys.

string
eta

On demand. Arrival band.

object
from
required
string format: date-time
to
required
string format: date-time
window

Window option.

object
start
required
string format: date-time
end
required
string format: date-time
cutoffAt

Window option. Book and cancel free before it.

string format: date-time
price
required
object
amountMinor
required

VAT included.

integer
vatMinor
integer
exVatMinor
integer
currency
required
string
supply

On demand only. HINT for the seller, never a promise: drivers near the store when quoted and when the first-ranked could reach it. Do not show a driver count to shoppers.

object
nearbyDrivers
required
integer
pickupEta
required
object
from
required
string format: date-time
to
required
string format: date-time

Example 

{
  "error": {
    "code": "invalid_request",
    "details": {
      "option": {
        "type": "on_demand",
        "key": "on_demand",
        "price": {
          "currency": "NOK"
        }
      }
    }
  }
}

429

Section titled “429”

rate_limited. Also after repeated failed sign-ins from one address.

Media typeapplication/json
object
error
required
object
code
required

Status per code: 400 malformed_json, idempotency_key_required; 401 unauthenticated; 403 merchant_suspended, insufficient_scope; 404 not_found, quote_not_found; 405 method_not_allowed; 409 conflict, cancellation_not_allowed, idempotency_key_in_flight, price_changed, option_unavailable, fee_changed, quote_already_used, external_ref_taken, window_full, order_ended; 422 invalid_request, idempotency_key_reused, no_delivery_options, manual_quote_required, invalid_address; 429 rate_limited; 500 internal; 503 unavailable.

string
Allowed values: invalid_request malformed_json not_found method_not_allowed unauthenticated merchant_suspended insufficient_scope conflict cancellation_not_allowed idempotency_key_required idempotency_key_reused idempotency_key_in_flight unavailable rate_limited quote_not_found no_delivery_options manual_quote_required invalid_address price_changed option_unavailable fee_changed quote_already_used external_ref_taken window_full order_ended internal
message
required

Human-readable; may change. Branch on code.

string
param

The request field at fault, e.g. delivery.address (an unknown field: its name).

string
requestId
string
details
One of:
object
quotedAmountMinor
required
integer
option
required
object
type
required
string
Allowed values: on_demand window
key
required

Stable key to book (on_demand or window:<start>/<end> in the market’s zone). The same delivery quoted again lists the same keys.

string
eta

On demand. Arrival band.

object
from
required
string format: date-time
to
required
string format: date-time
window

Window option.

object
start
required
string format: date-time
end
required
string format: date-time
cutoffAt

Window option. Book and cancel free before it.

string format: date-time
price
required
object
amountMinor
required

VAT included.

integer
vatMinor
integer
exVatMinor
integer
currency
required
string
supply

On demand only. HINT for the seller, never a promise: drivers near the store when quoted and when the first-ranked could reach it. Do not show a driver count to shoppers.

object
nearbyDrivers
required
integer
pickupEta
required
object
from
required
string format: date-time
to
required
string format: date-time

Example 

{
  "error": {
    "code": "invalid_request",
    "details": {
      "option": {
        "type": "on_demand",
        "key": "on_demand",
        "price": {
          "currency": "NOK"
        }
      }
    }
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait.

RateLimit-Limit
integer

Requests per minute for your merchant (600).

RateLimit-Remaining
integer
RateLimit-Reset
integer

Seconds until the window resets.

© 2026 Delivr ASSupportChangelogOpenAPIllms.txt