Webhooks

Webhooks let your integration receive real-time push notifications the moment something happens to an order, a shipment, or your wallet — without ever polling the API.

🔔

Instead of repeatedly asking the API "did anything change?", you register a public HTTPS endpoint once. Lamha then delivers a signed message to that endpoint automatically, every time an event you subscribed to occurs.

How it works

The flow at a glance

Subscribe — register your receiving URL for one or more events, with an optional shared secret.

An event happens — an order is created, a status changes, a label becomes ready, and so on.

Lamha delivers — a signed POST is pushed to your URL carrying the event name and its data.

You verify & act — you validate the signature, acknowledge the delivery, then process it on your side.

Each subscription is tied to a single event type. You can register multiple webhooks — for different events, or even different destinations for the same event.

Available events

Every webhook subscribes to exactly one of the following event types.

Event	Fires when
`order.created`	A new order is created.
`order.status.changed`	An order's status is updated.
`order.shipment.created`	A shipment is created for an order.
`order.shipment.cancelled`	A shipment is cancelled.
`order.national_address_status`	The national-address status changes.
`shipment.label.ready`	The shipping label (waybill) becomes ready.
`balance.deposit`	Funds are deposited into your wallet.
`balance.low`	Your wallet balance drops below the threshold.
`automation.failed`	An automation run fails.

Event conditions

Some events can be narrowed down so you only receive the deliveries that matter to you.

::accordion-item{title="Filter order status changes"}
For order.status.changed, you can restrict delivery to a specific set of order statuses (for example: only picked, delivered, and returned). If you don't specify any, every status change is delivered.
::
::accordion-item{title="Filter low-balance alerts"}
For balance.low, you can set a numeric threshold so the event only fires once your wallet balance drops below that value.
::

What a delivery looks like

When a subscribed event fires, Lamha pushes a signed message to your endpoint. Every delivery carries a small set of headers that describe and secure it:

Header	Meaning
`X-Webhook-Signature`	An `HMAC-SHA256` signature of the message body, signed with your secret.
`X-Webhook-Event`	The event name (e.g. `order.status.changed`).
`X-Webhook-Id`	A unique id for this delivery attempt — use it to avoid processing the same event twice.
`X-Webhook-Timestamp`	When the delivery was sent (ISO-8601).

The message body always contains three fields: the event name, its data, and a timestamp.

Acknowledge quickly

Return a 2xx response fast, then do any heavy work asynchronously. A non-2xx response is treated as a failure and the delivery is retried.

Security & verification

Always verify the signature

Never trust an incoming payload before checking its signature. Recompute the HMAC-SHA256 of the received body using your stored secret and compare it against the X-Webhook-Signature header. If they don't match, reject the request.

About the secret

The shared secret is what makes deliveries verifiable. If you don't provide one when subscribing, Lamha generates a strong secret for you — but it is shown only once, so store it safely. It is never returned again afterwards.

Verification ping

Automatic ownership check

As soon as you register an active webhook, Lamha sends a one-off verification delivery to confirm your endpoint is reachable and can validate signatures.

It arrives just like a normal delivery, but its event name ends with .verification and its data contains "verification": true. Treat it as a health check — acknowledge it with 2xx and don't process it as a real business event.

Webhooks Events

Webhooks#

How it works#

Available events#

Event conditions#

What a delivery looks like#

Security & verification#

Verification ping#