GROperator

جارٍ التحميل…

English

Webhooks

كل عمليات واجهة LastMile العامة، مولَّدة من وثيقة OpenAPI. نص المرجع بالإنجليزية في اللغتين.

GET

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

#

List the webhook subscriptions of a merchant

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: webhooks:manage

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

المعاملات

الاسمالموضعالنوعالوصف
merchantId
مطلوب
pathstring (uuid)

Merchant id.

مثال طلب

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"

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200The subscriptions (without secrets).

الاستجابات · الحقل
الحقلالنوعالوصف
idstring (uuid)

Subscription id.

merchantIdstring (uuid)

The merchant whose shipments trigger the events.

urlstringيقبل null

The receiving URL.

eventsarray<string>يقبل null

Subscribed event types.

descriptionstringيقبل null

Description.

isActiveboolean

False when the subscription is paused.

createdAtstring (date-time)

Creation time (UTC).

200 · مثال استجابة
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "isActive": false,
    "createdAt": "2026-01-15T09:30:00Z"
  }
]
الحالةالوصف
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.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

POST

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

#

Create a webhook subscription

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: 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).

المعاملات

الاسمالموضعالنوعالوصف
merchantId
مطلوب
pathstring (uuid)

Merchant id.

جسم الطلب · PublicCreateWebhookRequestapplication/json

The subscription.

الحقلالنوعالوصف
urlstringيقبل null

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

مثال: https://shop.example.com/hooks/lastmile

eventsarray<string>يقبل null

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

مثال: ["shipment.created","shipment.delivered"]

descriptionstringيقبل null

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

مثال: Order system

وثيقة OpenAPI لا تعلّم الحقول المطلوبة رسمياً، لذلك تُقرأ كلمة «مطلوب» من وصف كل حقل. تسرد الأدلة الحقول المطلوبة لكل طلب.

مثال طلب

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

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

201The subscription, including its secret.

الاستجابات · الحقل
الحقلالنوعالوصف
idstring (uuid)

Subscription id.

merchantIdstring (uuid)

The merchant whose shipments trigger the events.

urlstringيقبل null

The receiving URL.

eventsarray<string>يقبل null

Subscribed event types.

descriptionstringيقبل null

Description.

isActiveboolean

Whether it is active.

createdAtstring (date-time)

Creation time (UTC).

secretstringيقبل null

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

201 · مثال استجابة
{
  "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..."
}
الحالةالوصف
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.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

DELETE

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

#

Delete a webhook subscription

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: webhooks:manage

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

المعاملات

الاسمالموضعالنوعالوصف
merchantId
مطلوب
pathstring (uuid)

Merchant id.

id
مطلوب
pathstring (uuid)

Subscription id.

مثال طلب

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"

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

204Deleted. Past delivery logs are kept.

الحالةالوصف
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.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

POST

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

#

Rotate the signing secret

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: webhooks:manage

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

المعاملات

الاسمالموضعالنوعالوصف
merchantId
مطلوب
pathstring (uuid)

Merchant id.

id
مطلوب
pathstring (uuid)

Subscription id.

مثال طلب

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"

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200The new secret.

الاستجابات · الحقل
الحقلالنوعالوصف
secretstringيقبل null

The new signing secret.

200 · مثال استجابة
{}
الحالةالوصف
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.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

POST

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

#

Send a test event

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: 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.

المعاملات

الاسمالموضعالنوعالوصف
merchantId
مطلوب
pathstring (uuid)

Merchant id.

id
مطلوب
pathstring (uuid)

Subscription id.

مثال طلب

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"

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200The ping was queued.

الاستجابات · الحقل
الحقلالنوعالوصف
queuedboolean

True when a signed ping event was queued for delivery.

eventTypestringيقبل null

The event type sent (ping).

200 · مثال استجابة
{
  "queued": false
}
الحالةالوصف
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.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء

GET

/api/public/v1/webhooks/events

#

List webhook event types

مفتاح API وسرّه، أو رمز Bearerالنطاق المطلوب: 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.

مثال طلب

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"

تستخدم الأمثلة مفتاح API؛ استبدل القيم النائبة. لاستخدام رمز Bearer أرسل Authorization: Bearer <accessToken>.

الاستجابات

200The event catalog.

الاستجابات · الحقل
الحقلالنوعالوصف
typestringيقبل null

Event type, e.g. shipment.delivered.

descriptionstringيقبل null

When the event is sent.

examplePayloadanyيقبل null

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

200 · مثال استجابة
[
  {}
]
الحالةالوصف
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.

تشترك أخطاء الواجهة في جسم واحد موصوف في مرجع الأخطاء. مرجع الأخطاء