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://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"

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

الاستجابات

200The subscriptions (without secrets).

الاستجابات · الحقل
الحقلالنوعالوصف
id
مطلوب
string (uuid)

Subscription id.

merchantId
مطلوب
string (uuid)

The merchant whose shipments trigger the events.

url
مطلوب
string

The receiving URL.

events
مطلوب
array<string>

Subscribed event types.

descriptionstringيقبل null

Description.

isActive
مطلوب
boolean

False when the subscription is paused.

createdAt
مطلوب
string (date-time)

Creation time (UTC).

200 · مثال استجابة
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "string",
    "events": [
      "string"
    ],
    "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.

الحقلالنوعالوصف
url
مطلوب
string

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

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

events
مطلوب
array<string>

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

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

الاستجابات

201The subscription, including its secret.

الاستجابات · الحقل
الحقلالنوعالوصف
id
مطلوب
string (uuid)

Subscription id.

merchantId
مطلوب
string (uuid)

The merchant whose shipments trigger the events.

url
مطلوب
string

The receiving URL.

events
مطلوب
array<string>

Subscribed event types.

descriptionstringيقبل null

Description.

isActive
مطلوب
boolean

Whether it is active.

createdAt
مطلوب
string (date-time)

Creation time (UTC).

secret
مطلوب
string

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://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"

تستخدم الأمثلة مفتاح 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://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"

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

الاستجابات

200The new secret.

الاستجابات · الحقل
الحقلالنوعالوصف
secret
مطلوب
string

The new signing secret.

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

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

الاستجابات

200The ping was queued.

الاستجابات · الحقل
الحقلالنوعالوصف
queued
مطلوب
boolean

True when a signed ping event was queued for delivery.

eventType
مطلوب
string

The event type sent (ping).

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

الاستجابات · الحقل
الحقلالنوعالوصف
type
مطلوب
string

Event type, e.g. shipment.delivered.

description
مطلوب
string

When the event is sent.

examplePayload
مطلوب
any

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

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

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