# Webhooks: get notified when things change in your store

WEBHOOKS: GET NOTIFIED WHEN THINGS CHANGE IN YOUR STORE

Webhooks are the easiest way to wire LaunchMyStore into the rest of your
business. When something happens in your store — an order is paid, a product is
updated, a customer signs up — LMS calls a URL you control with the event
payload. No polling, no missed updates.


HOW LMS WEBHOOKS WORK

 1. You register a callback URL and a topic in your admin (or via the API).
 2. When that topic fires in your store, LMS dispatches the event to your URL
    with a JSON body.
 3. If your endpoint returns a 2xx response within 10 seconds, the delivery is
    logged as SUCCESS.
 4. If it fails or times out, LMS retries up to 3 times with exponential backoff
    (1 min, 5 min, 15 min) plus jitter.
 5. Permanent 4xx responses (except 429) skip retries.


SUPPORTED TOPICS

The platform currently dispatches the following webhook topics:

TopicWhen it fires orders/createA new order is created orders/updatedAn existing
order is updated orders/paidAn order is marked paid orders/cancelledAn order is
cancelled orders/fulfilledAll items on an order are fulfilled
fulfillments/createA fulfillment is created fulfillments/updateA fulfillment is
updated refunds/createA refund is recorded products/createA product is created
products/updateA product is updated products/deleteA product is deleted
collections/createA collection is created collections/updateA collection is
updated collections/deleteA collection is deleted customers/createA customer
signs up customers/updateA customer profile is updated customers/deleteA
customer is deleted carts/createA cart is started carts/updateA cart is modified
checkouts/createA checkout begins checkouts/updateA checkout is updated
discounts/createA discount is created discounts/updateA discount is updated
discounts/deleteA discount is deleted blogs/createA blog is created
blogs/updateA blog is updated blogs/deleteA blog is deleted
inventory/updateInventory levels change themes/publishA theme is published
themes/updateA theme is updated shop/updateStore settings change app/installedAn
app is installed app/uninstalledAn app is uninstalled newsletter/createA shopper
subscribes contact_form/createA shopper submits the contact form
customers/data_requestGDPR data request (mandatory) customers/redactGDPR
customer redact (mandatory) shop/redactGDPR shop redact (mandatory)


REGISTERING A WEBHOOK

You can register a webhook in admin under Settings → Notifications → Webhooks,
or via the REST API:

curl -X POST https://api.launchmystore.io/webhooks \
  -H "Authorization: Bearer <merchant-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "orders/paid",
    "callbackUrl": "https://example.com/lms/webhooks",
    "isEnabled": true
  }'

Apps register through the OAuth-scoped /api/v1/webhooks endpoints with a secret
for HMAC signing.


PAYLOAD STRUCTURE

Every delivery is a JSON POST with these headers:

 * X-LMS-Topic – the topic that fired, e.g. orders/paid.
 * X-LMS-Webhook-Id – unique delivery ID (use this for idempotency).
 * X-LMS-Delivery-Attempt – attempt number, starts at 1.
 * X-LMS-Hmac-SHA256 – base64 HMAC of the raw body (app webhooks only).

The body itself depends on the topic — for an order it contains the full
Shopify-compatible order object; for an inventory event it contains the SKU,
location, and new level.


RETRY POLICY

LMS retries deliveries up to 3 times:

 * Attempt 2 — 1 minute after attempt 1
 * Attempt 3 — 5 minutes after attempt 2
 * Attempt 4 — 15 minutes after attempt 3

Each delay has ±10% jitter to avoid thundering-herd retries. After 3 failed
attempts, the delivery is marked FAILED and you can re-trigger it manually from
the delivery log.


IDEMPOTENCY

Because deliveries may be retried, design your handler to be idempotent. The
recommended pattern: store X-LMS-Webhook-Id in your database the first time you
process it. If you see the same ID again, skip processing and return 200.


FAQ


WHAT’S THE DIFFERENCE BETWEEN MERCHANT WEBHOOKS AND APP WEBHOOKS?

Merchant webhooks are configured in your admin and don’t have a secret — they’re
unsigned. App webhooks are registered by an installed app, carry the app’s
secret, and include the X-LMS-Hmac-SHA256 header so the recipient can verify
authenticity.


WILL MY SERVER BE HAMMERED WITH RETRIES IF IT’S DOWN?

No. Retries are capped at 3 attempts spread across roughly 21 minutes. Permanent
4xx responses (except 429) skip retries entirely, so a bad URL won’t keep
firing.


HOW DO I SEE WHAT WAS SENT?

Open Settings → Notifications → Webhooks and click any webhook to view its
delivery log. Each row shows the attempt count, response code, response body
(truncated to 2000 chars) and any error.


CAN I SUBSCRIBE TO ALL TOPICS AT ONCE?

No — each subscription targets exactly one topic. Create one webhook per topic
you care about. This keeps payloads focused and makes delivery logs easier to
read.


WHAT’S THE TIMEOUT FOR MY ENDPOINT?

10 seconds. If you can’t complete processing in that window, return 200
immediately and queue the work for background processing.


ARE WEBHOOKS DELIVERED IN ORDER?

Not strictly. Retries can interleave with new events for the same resource. Use
timestamps in the payload (or your own ordering logic) when order matters.