Webhooks: Real-Time Commerce Event Streaming

Webhooks are the backbone of any real integration. Instead of polling the API every 30 seconds to check if a new order arrived, you register a URL and LetBuyy pushes events to you the moment they happen.

Available Event Types

• order.created, order.updated, order.fulfilled, order.cancelled
• payment.captured, payment.failed, payment.refunded
• product.created, product.updated, product.deleted
• inventory.low_stock, inventory.out_of_stock
• customer.created, customer.updated
• checkout.abandoned, checkout.completed

Registering a Webhook

POST /v1/webhooks
{
  "url": "https://yourapp.com/webhooks/letbuyy",
  "events": ["order.created", "payment.captured"],
  "secret": "your_webhook_secret"
}

Signature Verification (Critical)

Every webhook includes a X-LetBuyy-Signature header. Verify it before processing. LetBuyy signs the raw request body with your webhook secret using HMAC-SHA256.

import { createHmac, timingSafeEqual } from "crypto"

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex")
  const signatureBuffer = Buffer.from(signature, "hex")
  const expectedBuffer = Buffer.from(expected, "hex")
  return signatureBuffer.length === expectedBuffer.length &&
    timingSafeEqual(signatureBuffer, expectedBuffer)
}

Reliability Patterns

• Respond with HTTP 200 within 5 seconds — do heavy processing async
• LetBuyy retries failed deliveries: 1min, 5min, 30min, 2hr, 24hr
• Implement idempotency using the webhook ID (X-LetBuyy-Webhook-ID header)
• Store raw webhook payload before processing — enables replay on errors
• Expose a /webhooks/health endpoint for monitoring