Webhooks

A webhook tells your system that something changed in the merchant's Mekari POS: an order was paid, a kitchen ticket moved on, a product or collection changed, or a product sold out. Mekari POS sends a signed POST request with a small JSON body to an https URL you choose. You do not need to poll the API for changes.

Endpoint Keys

Events are grouped into four endpoint keys. Your application can set one URL per key for each merchant. Different keys can use the same URL.

Key	Events
`orders`	Order payment, returns, refunds, exchanges and kitchen status
`products`	Product changes and SKU changes
`collections`	Collection changes
`inventory`	A product at an outlet sells out or is back in stock

The full list of events is in Events.

Endpoints belong to your application and the merchant. Other applications cannot see or change them. Changes your own application makes through the API are not sent back to it, except inventory.availability_changed (see Events).

Before You Start

The merchant's plan must include the Public API add-on. Without it, the webhook endpoints answer 403 PLAN_FEATURE_REQUIRED (or 403 SUBSCRIPTION_EXPIRED when the plan has expired), and no events are sent.
Your application needs the scope of each operation it calls. All webhook scopes are under mekari-pos-open:v2:webhook:all.

Operation	Scope
`GET /webhooks/endpoints`	`mekari-pos-open:v2:webhook:endpoint:list`
`PUT /webhooks/endpoints/orders`	`mekari-pos-open:v2:webhook:orders:subscribe`
`PUT /webhooks/endpoints/products`	`mekari-pos-open:v2:webhook:products:subscribe`
`PUT /webhooks/endpoints/collections`	`mekari-pos-open:v2:webhook:collections:subscribe`
`PUT /webhooks/endpoints/inventory`	`mekari-pos-open:v2:webhook:inventory:subscribe`
`DELETE /webhooks/endpoints/{key}`	`mekari-pos-open:v2:webhook:endpoint:delete`
`POST /webhooks/endpoints/{key}/rotate-secret`	`mekari-pos-open:v2:webhook:secret:rotate`
`POST /webhooks/endpoints/{key}/test`	`mekari-pos-open:v2:webhook:endpoint:test`

Webhook operations work on the whole merchant: they need no X-Outlet-ID, no X-User-ID and no Idempotency-Key.

Set Up an Endpoint

Send PUT /webhooks/endpoints/{key} with the URL, the events you want and the payload type:

{
  "url": "https://partner.example/hooks/mekari-pos",
  "events": ["order.paid", "order.ready"],
  "payload": "thin"
}

Field	Rules
`url`	An absolute `https` URL on port 443, without user info before the host or a fragment (`#...`). `localhost` and private, loopback or link-local IP addresses are refused, and when events are sent the host name must resolve to a public address.
`events`	At least one event. Each event must belong to this key. Duplicates are ignored. The list replaces the previous list.
`payload`	`thin` (default) or `full`. The `inventory` key accepts `thin` only. See Thin and Full Payloads.

A field that breaks a rule answers 400 VALIDATION_FAILED with the field named in data.fields. To stop all events of a key, use DELETE (an empty events list is invalid).

The endpoint is active at once. Mekari POS does not send a challenge request first; use test to check your receiver.

PUT answers 201 when it created the endpoint and 200 when the endpoint already existed. Send the whole definition every time.

Save the Signing Secret

The response contains a secret object only when a new signing secret was issued:

{
  "status": "success",
  "message": "OK",
  "data": {
    "key": "orders",
    "url": "https://partner.example/hooks/mekari-pos",
    "events": ["order.paid", "order.ready"],
    "payload": "thin",
    "status": "active",
    "consecutive_failures": 0,
    "active_key_version": 1,
    "created_at": "2026-10-14T03:00:00Z",
    "updated_at": "2026-10-14T03:00:00Z",
    "secret": { "secret": "<SIGNING_SECRET>", "key_version": 1 }
  }
}

A new secret is issued when:

the endpoint is new;
you change its url (new requests are signed with the new secret at once; see rotation);
you set it again after a DELETE.

Changing only events or payload returns no secret. Store the secret when you get it. Mekari POS keeps it encrypted and never shows it again. Keep it with your other credentials, never in source code. You need it to verify signatures.

Test the Endpoint

POST /webhooks/endpoints/{key}/test sends one signed webhook.test event to the endpoint now and waits up to 10 seconds:

{ "status": "success", "message": "OK", "data": { "delivered": true, "http_status": 200, "error": null } }

Result	Meaning
`delivered: true`	Your receiver answered `2xx`.
`http_status` set, no `error`	Your receiver answered with that non-`2xx` status.
`error` set	No answer: `timeout`, `request failed` or `invalid webhook destination`. `http_status` is `null`.

The test event is signed like real events, so use it to check your signature code. Its data is {} and outlet_id is null. A test never pauses the endpoint and is not retried.

Manage Endpoints

Operation	What it does
`GET /webhooks/endpoints`	Lists your endpoints with `key`, `url`, `events`, `payload`, `status` (`active`, `paused` or `disabled`), `consecutive_failures` and `active_key_version`. Never the secret.
`DELETE /webhooks/endpoints/{key}`	Stops the endpoint: nothing more is sent, waiting deliveries are cancelled and its secrets stop working. It stays in the list as `disabled`. Answers `204`.
`POST /webhooks/endpoints/{key}/rotate-secret`	Issues a new secret and `key_version`. New requests are signed with it at once; the previous secret is revoked after 24 hours. See Rotating the Secret.
`POST /webhooks/endpoints/{key}/test`	Sends a test event (above).

DELETE, rotate-secret and test answer 404 NOT_FOUND for an unknown key or an endpoint you have not set or have deleted.

A paused endpoint (after repeated failures) is active again after a PUT. See Pausing.

API Reference

Next Steps

Read Events to choose your events and payload type.
Implement Verifying Signatures in your receiver.
Read Delivery and Retries to answer correctly and handle duplicates.

Endpoint Keys​

Before You Start​

Set Up an Endpoint​

Save the Signing Secret​

Test the Endpoint​

Manage Endpoints​

API Reference​

Next Steps​