Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.launchmystore.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Webhooks

Webhooks allow your app to receive real-time notifications when events occur in a merchant’s store. Instead of polling for changes, LaunchMyStore pushes events to your server as they happen.

​
How Webhooks Work

​
Registering Webhooks

Register webhooks during app installation: 
const response = await fetch('https://api.launchmystore.io/api/v1/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    topic: 'orders/create',
    address: 'https://my-app.com/webhooks/orders',
    format: 'json'
  })
});

​
Webhook Topics

LaunchMyStore supports 31 webhook topics:

​
Orders

TopicDescription
orders/createNew order placed
orders/updatedOrder modified
orders/cancelledOrder cancelled
orders/fulfilledOrder fully fulfilled
orders/paidOrder payment confirmed

​
Products

TopicDescription
products/createNew product created
products/updateProduct modified
products/deleteProduct deleted

​
Customers

TopicDescription
customers/createNew customer registered
customers/updateCustomer data modified
customers/deleteCustomer deleted

​
Inventory

TopicDescription
inventory/updateInventory level changed

​
Checkouts

TopicDescription
checkouts/createCheckout started
checkouts/updateCheckout modified
checkouts/completeCheckout completed

​
App

TopicDescription
app/installedApp installed on store
app/uninstalledApp removed from store
See Webhook Topics for the complete list.

​
Webhook Payload

{
  "id": "webhook_abc123",
  "topic": "orders/create",
  "shop_domain": "merchant-store.launchmystore.io",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    // Event-specific data (e.g., order object)
  }
}

​
Verifying Webhooks

All webhooks are signed with HMAC-SHA256. Verify the signature to ensure the webhook came from LaunchMyStore: 
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload, 'utf8').digest('base64');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

// In your webhook handler
app.post('/webhooks/orders', (req, res) => {
  const signature = req.headers['x-lms-hmac-sha256'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  const { topic, data } = req.body;
  // ...
  
  res.status(200).send('OK');
});

​
Delivery & Retries

  • Timeout: Your endpoint must respond within 5 seconds
  • Response: Return 2xx status code to acknowledge receipt
  • Retries: Failed deliveries are retried 3 times with exponential backoff:
    • 1st retry: 1 minute
    • 2nd retry: 5 minutes
    • 3rd retry: 15 minutes
  • Dead letter: After 3 failures, the webhook is logged and no more retries

​
Best Practices

Return 200 immediately, then process asynchronously. Long-running handlers cause timeouts.
Webhooks may be delivered more than once. Use the id field to deduplicate.
Always verify HMAC signatures to ensure webhooks are authentic.
Webhook endpoints must use HTTPS in production.

​
Managing Webhooks

​
List Webhooks

GET /api/v1/webhooks

​
Delete Webhook

DELETE /api/v1/webhooks/{webhook_id}