Events & Webhooks

Because WebbiOS Apps run as isolated Cloudflare Workers, they rely on an Event-Driven Architecture to know when things happen in the merchant’s store.

The Webhook System

Whenever a significant action occurs in the WebbiOS Core (e.g., a customer places an order, a product is updated, or a new user registers), the Core API emits an event.

Apps can subscribe to these events using Webhooks.

1. Registering Webhooks

When your app is installed, you can use the @webbi/sdk to register endpoints that should be called when specific events occur.

// Example: Registering a webhook during app initialization
await sdk.webhooks.register({
  topic: 'orders/create',
  address: 'https://your-app-worker.dev/webhooks/orders-create',
  format: 'json'
});

2. Receiving Webhooks

Your App Worker must expose an HTTP POST endpoint to receive the webhook payload. The payload will contain the data related to the event.

// Example Worker endpoint handling the webhook
app.post('/webhooks/orders-create', async (c) => {
  const payload = await c.req.json();

  // Verify the webhook signature to ensure it came from WebbiOS Core
  // Process the order...
  console.log('New order received:', payload.order.id);

  return c.text('OK');
});

Security

It is critical to verify the authenticity of incoming webhooks. Every webhook request includes an x-webbios-signature header. Your app should use its shared secret to compute an HMAC of the raw request body and compare it against the header.