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://api.goldrock.live/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
idstring (uuid)

Subscription id.

merchantIdstring (uuid)

The merchant whose shipments trigger the events.

urlstringnullable

The receiving URL.

eventsarray<string>nullable

Subscribed event types.

descriptionstringnullable

Description.

isActiveboolean

False when the subscription is paused.

createdAtstring (date-time)

Creation time (UTC).

200 · Example response
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "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
urlstringnullable

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

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

eventsarray<string>nullable

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://api.goldrock.live/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
idstring (uuid)

Subscription id.

merchantIdstring (uuid)

The merchant whose shipments trigger the events.

urlstringnullable

The receiving URL.

eventsarray<string>nullable

Subscribed event types.

descriptionstringnullable

Description.

isActiveboolean

Whether it is active.

createdAtstring (date-time)

Creation time (UTC).

secretstringnullable

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://api.goldrock.live/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://api.goldrock.live/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
secretstringnullable

The new signing secret.

200 · Example response
{}
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://api.goldrock.live/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
queuedboolean

True when a signed ping event was queued for delivery.

eventTypestringnullable

The event type sent (ping).

200 · Example response
{
  "queued": false
}
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://api.goldrock.live/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
typestringnullable

Event type, e.g. shipment.delivered.

descriptionstringnullable

When the event is sent.

examplePayloadanynullable

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

200 · Example response
[
  {}
]
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