GROperator

Webhooks

Every operation of the LastMile Public API, generated from the OpenAPI document. The reference text is in English in both languages.

GET

/api/public/v1/merchants/{merchantId}/webhooks

#

List the webhook subscriptions of a merchant

API key + secret, or bearer tokenRequired scope: webhooks:manage

Required scope (API key) or equivalent permission (password): webhooks:manage.

Parameters

NameInTypeDescription
merchantId
required
pathstring (uuid)

Merchant id.

Request example

GET /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks
curl "https://apiv1.groperator.com/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The subscriptions (without secrets).

Responses · Field
FieldTypeDescription
id
required
string (uuid)

Subscription id.

merchantId
required
string (uuid)

The merchant whose shipments trigger the events.

url
required
string

The receiving URL.

events
required
array<string>

Subscribed event types.

descriptionstringnullable

Description.

isActive
required
boolean

False when the subscription is paused.

createdAt
required
string (date-time)

Creation time (UTC).

200 · Example response
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "string",
    "events": [
      "string"
    ],
    "isActive": false,
    "createdAt": "2026-01-15T09:30:00Z"
  }
]
StatusDescription
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code merchant.not_found.

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

POST

/api/public/v1/merchants/{merchantId}/webhooks

#

Create a webhook subscription

API key + secret, or bearer tokenRequired scope: webhooks:manage

The response contains the signing secret. It is shown only now; store it. Use it to verify the signature of every delivery (see the description of this section).

Parameters

NameInTypeDescription
merchantId
required
pathstring (uuid)

Merchant id.

Request body · PublicCreateWebhookRequestapplication/json

The subscription.

FieldTypeDescription
url
required
string

HTTPS URL that receives the events. Private and local addresses are refused.

Example: https://shop.example.com/hooks/lastmile

events
required
array<string>

Event types to receive, from GET /webhooks/events. Wildcards: shipment.* (all shipment events) or * (everything). At least one.

Example: ["shipment.created","shipment.delivered"]

descriptionstringnullable

Free text to recognise the subscription (optional, up to 200 characters).

Example: Order system

The OpenAPI document does not mark required fields formally, so “required” is read from each field’s description. The guides list the required fields of every request.

Request example

POST /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks
curl -X POST "https://apiv1.groperator.com/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://shop.example.com/hooks/lastmile",
  "events": [
    "shipment.created",
    "shipment.out_for_delivery",
    "shipment.delivered"
  ],
  "description": "Order system"
}'

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

201The subscription, including its secret.

Responses · Field
FieldTypeDescription
id
required
string (uuid)

Subscription id.

merchantId
required
string (uuid)

The merchant whose shipments trigger the events.

url
required
string

The receiving URL.

events
required
array<string>

Subscribed event types.

descriptionstringnullable

Description.

isActive
required
boolean

Whether it is active.

createdAt
required
string (date-time)

Creation time (UTC).

secret
required
string

Signing secret: keep it safe, use it to verify the X-Signature header of every delivery.

201 · Example response
{
  "id": "c1d6a1de-2f0e-4a7b-9c5e-6a3f6f0a9b11",
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://shop.example.com/hooks/lastmile",
  "events": [
    "shipment.created",
    "shipment.out_for_delivery",
    "shipment.delivered"
  ],
  "description": "Order system",
  "isActive": true,
  "createdAt": "2026-01-15T09:00:00Z",
  "secret": "5f1c0a7e9d3b..."
}
StatusDescription
400

The request is invalid (code validation_failed, details.errors lists every field).

401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code merchant.not_found.

422

A business rule or a location could not be satisfied (codes such as geo_city_not_found, shipment.cannot_cancel).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

DELETE

/api/public/v1/merchants/{merchantId}/webhooks/{id}

#

Delete a webhook subscription

API key + secret, or bearer tokenRequired scope: webhooks:manage

Required scope (API key) or equivalent permission (password): webhooks:manage.

Parameters

NameInTypeDescription
merchantId
required
pathstring (uuid)

Merchant id.

id
required
pathstring (uuid)

Subscription id.

Request example

DELETE /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6
curl -X DELETE "https://apiv1.groperator.com/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

204Deleted. Past delivery logs are kept.

StatusDescription
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code merchant.not_found or webhook.not_found.

422

A business rule or a location could not be satisfied (codes such as geo_city_not_found, shipment.cannot_cancel).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

POST

/api/public/v1/merchants/{merchantId}/webhooks/{id}/rotate-secret

#

Rotate the signing secret

API key + secret, or bearer tokenRequired scope: webhooks:manage

The new secret is returned once and the old one stops working immediately.

Parameters

NameInTypeDescription
merchantId
required
pathstring (uuid)

Merchant id.

id
required
pathstring (uuid)

Subscription id.

Request example

POST /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks/c1d6a1de-2f0e-4a7b-9c5e-6a3f6f0a9b11/rotate-secret
curl -X POST "https://apiv1.groperator.com/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks/c1d6a1de-2f0e-4a7b-9c5e-6a3f6f0a9b11/rotate-secret" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The new secret.

Responses · Field
FieldTypeDescription
secret
required
string

The new signing secret.

200 · Example response
{
  "secret": "string"
}
StatusDescription
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code merchant.not_found or webhook.not_found.

422

A business rule or a location could not be satisfied (codes such as geo_city_not_found, shipment.cannot_cancel).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

POST

/api/public/v1/merchants/{merchantId}/webhooks/{id}/test

#

Send a test event

API key + secret, or bearer tokenRequired scope: webhooks:manage

Queues a signed ping delivery ({ "event": "ping", "occurredAt": ..., "data": { "message": ..., "subscriptionId": ... } }) to the subscription's URL, exactly like a real event. Only active subscriptions can be tested.

Parameters

NameInTypeDescription
merchantId
required
pathstring (uuid)

Merchant id.

id
required
pathstring (uuid)

Subscription id.

Request example

POST /merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks/c1d6a1de-2f0e-4a7b-9c5e-6a3f6f0a9b11/test
curl -X POST "https://apiv1.groperator.com/api/public/v1/merchants/3fa85f64-5717-4562-b3fc-2c963f66afa6/webhooks/c1d6a1de-2f0e-4a7b-9c5e-6a3f6f0a9b11/test" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The ping was queued.

Responses · Field
FieldTypeDescription
queued
required
boolean

True when a signed ping event was queued for delivery.

eventType
required
string

The event type sent (ping).

200 · Example response
{
  "queued": false,
  "eventType": "string"
}
StatusDescription
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

404

Code merchant.not_found or webhook.not_found.

422

A business rule or a location could not be satisfied (codes such as geo_city_not_found, shipment.cannot_cancel).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference

GET

/api/public/v1/webhooks/events

#

List webhook event types

API key + secret, or bearer tokenRequired scope: webhooks:manage

Every event type you can subscribe to, with a description and an example payload. Use shipment.* to receive all shipment events or * for everything.

Request example

GET /webhooks/events
curl "https://apiv1.groperator.com/api/public/v1/webhooks/events" \
  -H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: YOUR_API_SECRET"

Samples use an API key; replace the placeholders. To use a bearer token instead, send Authorization: Bearer <accessToken>.

Responses

200The event catalog.

Responses · Field
FieldTypeDescription
type
required
string

Event type, e.g. shipment.delivered.

description
required
string

When the event is sent.

examplePayload
required
any

An example of the JSON body of the delivery (event, occurredAt, data).

200 · Example response
[
  {
    "type": "string",
    "description": "string"
  }
]
StatusDescription
401

Authentication is missing or invalid (code unauthorized).

403

The credential lacks the required scope, or the public API is disabled (codes forbidden, channel_disabled).

429

Too many requests (code rate_limited); wait for the Retry-After header.

Error responses share one body, described in the error reference. Error reference