Real-Time Updates with Webhooks

We're excited to announce enhanced webhook capabilities that enable real-time updates across your entire commerce stack.

What Are Webhooks?

Webhooks are HTTP callbacks that notify your application when events occur in NoPOS. Instead of polling our API, webhooks push updates to your application instantly.

Supported Events

Our webhook system supports a comprehensive set of events:

Inventory Events - `inventory.updated` - Stock levels changed - `inventory.low_stock` - Item below reorder point - `product.created` - New product added - `product.updated` - Product details changed

Transaction Events - `transaction.created` - New sale initiated - `transaction.completed` - Sale finalized - `transaction.refunded` - Refund processed - `payment.succeeded` - Payment confirmed - `payment.failed` - Payment declined

Customer Events - `customer.created` - New customer registered - `customer.updated` - Customer profile changed - `loyalty.points_earned` - Customer earned points - `loyalty.reward_redeemed` - Customer redeemed reward

Setting Up Webhooks

Configure webhooks through the API or dashboard:

const webhook = await fetch('https://api.nopos.dev/v1/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://your-app.com/webhooks/nopos',
    events: [
      'transaction.completed',
      'inventory.low_stock',
      'payment.succeeded'
    ],
    secret: 'your_webhook_secret'
  })
});

Handling Webhook Events

Implement an endpoint to receive webhooks:

app.post('/webhooks/nopos', async (req, res) => {
  // Verify webhook signature
  const signature = req.headers['x-nopos-signature'];
  const isValid = verifySignature(req.body, signature);
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the event
  const event = req.body;
  
  switch (event.type) {
    case 'transaction.completed':
      await handleTransactionComplete(event.data);
      break;
    case 'inventory.low_stock':
      await handleLowStock(event.data);
      break;
    case 'payment.succeeded':
      await handlePaymentSuccess(event.data);
      break;
  }
  
  res.status(200).send('OK');
});

Webhook Payload Structure

All webhooks follow a consistent format:

{
  "id": "evt_1234567890",
  "type": "transaction.completed",
  "created_at": "2024-11-10T10:30:00Z",
  "data": {
    "transaction_id": "txn_9876543210",
    "amount": 125.50,
    "status": "completed",
    "customer_id": "cust_123456"
  }
}

Retry Logic

NoPOS automatically retries failed webhook deliveries:

Initial attempt: Immediate
Retry 1: After 5 minutes
Retry 2: After 30 minutes
Retry 3: After 2 hours
Retry 4: After 12 hours

Best Practices

**Return 200 Quickly**: Process events asynchronously
**Verify Signatures**: Always validate webhook authenticity
**Handle Duplicates**: Implement idempotency
**Monitor Failures**: Set up alerts for webhook errors

Use Cases

Real-Time Inventory Sync

Keep your e-commerce platform updated:

async function handleInventoryUpdate(data) {
  await shopify.updateInventory({
    variant_id: data.variant_id,
    quantity: data.quantity,
    location_id: data.location_id
  });
}

Order Notifications

Send instant confirmations to customers:

async function handleTransactionComplete(data) {
  await sendEmail({
    to: data.customer_email,
    subject: 'Order Confirmed',
    template: 'order_confirmation',
    data: data
  });
}

Low Stock Alerts

Automate reordering:

async function handleLowStock(data) {
  if (data.quantity < data.reorder_point) {
    await createPurchaseOrder({
      product_id: data.product_id,
      quantity: data.reorder_quantity,
      supplier_id: data.supplier_id
    });
  }
}

Testing Webhooks

Use our webhook testing tool to simulate events:

curl -X POST https://api.nopos.dev/v1/webhooks/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_id": "wh_123456",
    "event_type": "transaction.completed"
  }'

What's Next?

We're continuously expanding webhook capabilities:

GraphQL subscriptions for real-time data
Webhook event filtering and transformation
Enhanced delivery analytics
Custom event definitions

Visit the Developer Portal for complete webhook documentation.