Webhooks

Receive real-time notifications when events occur in your store. Configure webhook endpoints to process chat messages, product recommendations, and analytics.

Registering a Webhook

webhook.ts

typescript

import { AICommerce } from '@yassirbenmoussa/aicommerce-sdk';

const client = new AICommerce({
  apiKey: 'YOUR_API_KEY',
});

// Register a webhook endpoint
const webhook = await client.webhooks.create({
  url: 'https://your-domain.com/webhooks/aicommerce',
  events: ['chat.message.received', 'product.viewed'],
  secret: 'your-webhook-secret'
});

console.log('Webhook ID:', webhook.id);

Webhook Payload

All webhooks include a signature header for verification and a standard payload structure.

webhook-payload.json

json

// Webhook payload example
{
  "event": "chat.message.received",
  "timestamp": "2024-01-15T10:30:00Z",
  "signature": "sha256=abc123...",
  "data": {
    "sessionId": "sess_abc123",
    "storeId": "store_xyz",
    "message": "Looking for running shoes",
    "products": [
      {
        "id": "prod_xyz",
        "name": "Nike Air Max",
        "relevanceScore": 0.95
      }
    ]
  }
}

Security

Always verify webhook signatures before processing. Never trust webhook data without verification.

Verifying Signatures

Use HMAC-SHA256 to verify webhook authenticity. Your webhook secret is available in the dashboard.

verify-webhook.ts

typescript

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string, 
  signature: string, 
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

// In your webhook handler
app.post('/webhooks/aicommerce', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process webhook...
  res.status(200).json({ received: true });
});

Available Events

Event	Description
chat.session.created	New chat session started
chat.message.received	User sent a message
chat.message.sent	AI responded with products
product.viewed	User clicked on a recommended product
product.added	New product added to catalog
product.updated	Product was updated
analytics.daily	Daily analytics summary

Tip

Webhooks are retried up to 3 times with exponential backoff if your endpoint returns a non-2xx status code.

Chat Widget

Examples

Registering a Webhook

webhook.ts

typescript

import { AICommerce } from '@yassirbenmoussa/aicommerce-sdk';

const client = new AICommerce({
  apiKey: 'YOUR_API_KEY',
});

// Register a webhook endpoint
const webhook = await client.webhooks.create({
  url: 'https://your-domain.com/webhooks/aicommerce',
  events: ['chat.message.received', 'product.viewed'],
  secret: 'your-webhook-secret'
});

console.log('Webhook ID:', webhook.id);

Webhook Payload

All webhooks include a signature header for verification and a standard payload structure.

webhook-payload.json

json

// Webhook payload example
{
  "event": "chat.message.received",
  "timestamp": "2024-01-15T10:30:00Z",
  "signature": "sha256=abc123...",
  "data": {
    "sessionId": "sess_abc123",
    "storeId": "store_xyz",
    "message": "Looking for running shoes",
    "products": [
      {
        "id": "prod_xyz",
        "name": "Nike Air Max",
        "relevanceScore": 0.95
      }
    ]
  }
}

Security

Always verify webhook signatures before processing. Never trust webhook data without verification.

Verifying Signatures

Use HMAC-SHA256 to verify webhook authenticity. Your webhook secret is available in the dashboard.

verify-webhook.ts

typescript

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string, 
  signature: string, 
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

// In your webhook handler
app.post('/webhooks/aicommerce', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process webhook...
  res.status(200).json({ received: true });
});

Available Events

Event	Description
chat.session.created	New chat session started
chat.message.received	User sent a message
chat.message.sent	AI responded with products
product.viewed	User clicked on a recommended product
product.added	New product added to catalog
product.updated	Product was updated
analytics.daily	Daily analytics summary

Tip

Webhooks are retried up to 3 times with exponential backoff if your endpoint returns a non-2xx status code.