Webhook Setup Guide

Overview

Emporiqa uses webhooks to receive product and page data from your e-commerce store. Instead of polling your store for updates, your store pushes data to us whenever changes occur.

Benefits of webhooks:

• Real-time updates - changes reflect immediately
• Efficient - only changed data is sent
• Store-controlled - you decide when to sync
• Batch support - send multiple events in one request

Getting Your Webhook URL

Your unique webhook URL is available in your store dashboard. It follows this format:

To find your webhook URL:

1. Log in to your Emporiqa dashboard
2. Go to your store's Settings page
3. Navigate to the Integration tab
4. Copy the Webhook URL shown there

Authentication

All webhook requests must include an HMAC-SHA256 signature for authentication. A connection secret is automatically generated when you create a store.

Setting Up Signature Verification

1. Copy the connection secret from your store settings
2. Store this secret securely in your application
3. Include the signature in the X-Webhook-Signature header

Generating the Signature

The signature is an HMAC-SHA256 hash of the raw request body using your connection secret:

import hmac
import hashlib

signature = hmac.new(
    webhook_secret.encode(),
    request_body,
    hashlib.sha256
).hexdigest()

headers = {
    "X-Webhook-Signature": signature,
    "Content-Type": "application/json"
}

Event Types

Emporiqa supports the following event types:

{
  "type": "product.availability",
  "data": {
    "identification_number": "product-123",   // or "variation-456"
    "sku": "ABC-123",
    "availability_statuses": { "": "out_of_stock" },   // per channel: available | out_of_stock | backorder | preorder
    "stock_quantities":      { "": 0 }                 // per channel: integer or null (untracked)
  }
}

Payload Format

Single Event

{
  "type": "product.created",
  "data": {
    "identification_number": "PROD-123",
    "sku": "WJ-001-M",
    "channels": ["default"],
    "names": {"default": {"en": "Winter Jacket"}},
    ...
  }
}

Batch Events

Send multiple events in a single request for better performance:

{
  "events": [
    {
      "type": "product.created",
      "data": { ... }
    },
    {
      "type": "product.updated",
      "data": { ... }
    },
    {
      "type": "page.created",
      "data": { ... }
    }
  ]
}

Product Events

ProductEventData Fields

Example Product Event

{
  "type": "product.created",
  "data": {
    "identification_number": "PROD-123",
    "sku": "WJ-001-M-BLK",
    "channels": ["default"],
    "names": {
      "default": {"en": "Winter Jacket - Waterproof"}
    },
    "descriptions": {
      "default": {"en": "Stay warm with our premium waterproof winter jacket..."}
    },
    "links": {
      "default": {"en": "https://example.com/products/winter-jacket"}
    },
    "categories": {
      "default": {"en": ["Clothing > Jackets > Winter"]}
    },
    "brands": {"default": "OutdoorPro"},
    "prices": {
      "default": [
        {
          "currency": "EUR",
          "current_price": 149.99,
          "regular_price": 199.99,
          "price_incl_tax": 149.99,
          "price_excl_tax": 126.04
        }
      ]
    },
    "availability_statuses": {"default": "available"},
    "stock_quantities": {"default": 25},
    "min_order_quantities": {"default": 1},
    "max_order_quantities": {"default": null},
    "available_for_order": true,
    "condition": "new",
    "is_virtual": false,
    "attributes": {
      "default": {"en": {"Color": "Black", "Size": "Medium", "Material": "Polyester"}}
    },
    "images": {
      "default": ["https://example.com/images/jacket-front.jpg", "https://example.com/images/jacket-back.jpg"]
    }
  }
}

Price Object Fields

Each entry in the prices array represents a price in a specific currency:

Multi-Currency Example

Add one price entry per currency your store sells in:

"prices": {
  "default": [
    {"currency": "EUR", "current_price": 149.99, "regular_price": 199.99},
    {"currency": "GBP", "current_price": 129.99},
    {"currency": "USD", "current_price": 159.99}
  ]
}

Page Events

Pages are used for policy documents, FAQ pages, shipping information, and other non-product content that customers might ask about.

PageEventData Fields

Example Page Event

{
  "type": "page.created",
  "data": {
    "identification_number": "PAGE-SHIPPING",
    "channels": ["default"],
    "titles": {
      "default": {"en": "Shipping Policy"}
    },
    "contents": {
      "default": {"en": "<h2>Shipping Information</h2><p>We offer free shipping on orders over $50...</p>"}
    },
    "links": {
      "default": {"en": "https://example.com/pages/shipping-policy"}
    }
  }
}

Delete Events

Only identification_number is required. The entire entity is deleted across all languages and channels:

{
  "type": "product.deleted",
  "data": {
    "identification_number": "PROD-123"
  }
}

Full Sync (Reconciliation)

Use sync sessions to perform a full data reconciliation. This is useful for:

• Initial data sync
• Periodic full sync to ensure data consistency
• Recovering from missed webhook events
• Removing products/pages that no longer exist in your store

Sync Session Flow

Step 1: Start Sync Session

{
  "type": "sync.start",
  "data": {
    "session_id": "sync-2024-01-15-abc123",
    "entity": "products"
  }
}

Step 2: Send Products/Pages with Session ID

Include the sync_session_id in each event to register it with the sync session:

{
  "events": [
    {
      "type": "product.updated",
      "data": {
        "identification_number": "PROD-001",
        "sku": "SKU-001",
        "names": {"default": {"en": "Product One"}},
        "sync_session_id": "sync-2024-01-15-abc123",
        ...
      }
    },
    {
      "type": "product.updated",
      "data": {
        "identification_number": "PROD-002",
        "sku": "SKU-002",
        "names": {"default": {"en": "Product Two"}},
        "sync_session_id": "sync-2024-01-15-abc123",
        ...
      }
    }
  ]
}

Step 3: Complete Sync Session

After sending all products/pages, complete the session. Any items not seen during the session will be marked as deleted:

{
  "type": "sync.complete",
  "data": {
    "session_id": "sync-2024-01-15-abc123",
    "entity": "products"
  }
}

SyncStartEventData / SyncCompleteEventData Fields

Response Codes

Success Response

On success, the webhook returns HTTP 202 Accepted:

{
  "status": "accepted",
  "queued": 5,
  "errors": []
}

Error Responses

Handling 429: Rate Limits and Backpressure

A 429 with a Retry-After header means one of two things. The response body tells you which:

The reason value is informational — it tells you which limit we reached, not what you should do differently. There is nothing to tune on your side for any of the four.

In particular, do not:

• Do not restart the sync from the first product. Nothing you already sent was lost.
• Do not abandon the sync or report it as failed. A 429 is not an error condition.
• Do not drop to one request per Retry-After interval. This is the expensive mistake: pausing and then sending a single batch per minute turns an import that would finish in a few hours into one that takes days. Pause once, then resume the loop.

Example: a loop that handles both cases

import time

def post_batch(events):
    """Sign and POST one batch, returning the raw HTTP response.

    Same signing as the send_webhook() example above, but returns the
    response object rather than the parsed body so we can read the
    status code and the Retry-After header.
    """
    payload = json.dumps({"events": events}).encode()
    signature = hmac.new(
        WEBHOOK_SECRET.encode(), payload, hashlib.sha256
    ).hexdigest()
    return requests.post(
        WEBHOOK_URL,
        data=payload,
        headers={
            "Content-Type": "application/json",
            "X-Webhook-Signature": signature,
        },
    )


def send_batch_with_backoff(events, max_attempts=10):
    """Send one batch. Returns when it has been accepted."""
    for attempt in range(max_attempts):
        response = post_batch(events)

        if response.status_code not in (429, 503):
            return response

        # A rate limit, ingestion backpressure, or a transient 503.
        # Same response to all three: wait the requested time, then send
        # this same batch again. Do NOT skip it, and do NOT restart the
        # whole sync.
        wait = int(response.headers.get("Retry-After", 60))
        time.sleep(wait)

    raise RuntimeError("Batch still refused after %d attempts" % max_attempts)


# Send the whole catalogue. The loop keeps running at full speed; only
# the batch that was actually refused waits.
send_batch_with_backoff([sync_start_event])       # never shed
for batch in batches_of(all_products, size=100):
    send_batch_with_backoff(batch)
send_batch_with_backoff([sync_complete_event])    # never shed

Code Examples

Python

import hmac
import hashlib
import json
import requests

WEBHOOK_URL = "https://emporiqa.com/webhooks/sync/YOUR_STORE_ID/"
WEBHOOK_SECRET = "your_webhook_secret"

def send_webhook(events):
    payload = json.dumps({"events": events}).encode()

    signature = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    headers = {
        "Content-Type": "application/json",
        "X-Webhook-Signature": signature,
    }

    response = requests.post(WEBHOOK_URL, data=payload, headers=headers)
    return response.json()

# Example: Create a product
result = send_webhook([{
    "type": "product.created",
    "data": {
        "identification_number": "PROD-123",
        "sku": "SKU-001",
        "channels": ["default"],
        "names": {"default": {"en": "My Product"}},
        "descriptions": {"default": {"en": "Product description here"}},
        "links": {"default": {"en": "https://mystore.com/products/my-product"}},
        "categories": {"default": {"en": ["Electronics"]}},
        "brands": {"default": "MyBrand"},
        "prices": {"default": [
            {"currency": "EUR", "current_price": 79.99, "regular_price": 99.99}
        ]},
        "availability_statuses": {"default": "available"}
    }
}])
print(result)

JavaScript (Node.js)

const crypto = require('crypto');

const WEBHOOK_URL = 'https://emporiqa.com/webhooks/sync/YOUR_STORE_ID/';
const WEBHOOK_SECRET = 'your_webhook_secret';

async function sendWebhook(events) {
    const payload = JSON.stringify({ events });

    const signature = crypto
        .createHmac('sha256', WEBHOOK_SECRET)
        .update(payload)
        .digest('hex');

    const headers = {
        'Content-Type': 'application/json',
        'X-Webhook-Signature': signature,
    };

    const response = await fetch(WEBHOOK_URL, {
        method: 'POST',
        headers,
        body: payload
    });

    return response.json();
}

// Example usage
sendWebhook([{
    type: 'product.created',
    data: {
        identification_number: 'PROD-123',
        sku: 'SKU-001',
        channels: [''],
        names: {'': {en: 'My Product'}},
        descriptions: {'': {en: 'Product description here'}},
        links: {'': {en: 'https://mystore.com/products/my-product'}},
        categories: {'': {en: ['Electronics']}},
        brands: {'': 'MyBrand'},
        prices: {'': [
            { currency: 'EUR', current_price: 79.99, regular_price: 99.99 }
        ]},
        availability_statuses: {'': 'available'}
    }
}]).then(console.log);

PHP

<?php
$webhookUrl = 'https://emporiqa.com/webhooks/sync/YOUR_STORE_ID/';
$webhookSecret = 'your_webhook_secret';

function sendWebhook($events) {
    global $webhookUrl, $webhookSecret;

    $payload = json_encode(['events' => $events]);

    $signature = hash_hmac('sha256', $payload, $webhookSecret);

    $headers = [
        'Content-Type: application/json',
        'X-Webhook-Signature: ' . $signature,
    ];

    $ch = curl_init($webhookUrl);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

// Example usage
$result = sendWebhook([[
    'type' => 'product.created',
    'data' => [
        'identification_number' => 'PROD-123',
        'sku' => 'SKU-001',
        'channels' => [''],
        'names' => ['' => ['en' => 'My Product']],
        'descriptions' => ['' => ['en' => 'Product description here']],
        'links' => ['' => ['en' => 'https://mystore.com/products/my-product']],
        'categories' => ['' => ['en' => ['Electronics']]],
        'brands' => ['' => 'MyBrand'],
        'prices' => ['' => [
            ['currency' => 'EUR', 'current_price' => 79.99, 'regular_price' => 99.99]
        ]],
        'availability_statuses' => ['' => 'available']
    ]
]]);
print_r($result);
?>

Troubleshooting

Order Completed Webhook (Conversion Tracking)

Send an order.completed event when a customer completes a purchase. Emporiqa uses this to attribute sales to chat sessions and display revenue data on your conversion tracking dashboard.

How It Works

1. Customer interacts with the chat widget (the widget stores a session ID in the browser)
2. Customer completes a purchase on your store
3. Your store sends an order.completed event to the Emporiqa webhook endpoint
4. Emporiqa links the purchase to the chat session and records the conversion
5. Revenue and conversion data appear on your dashboard

OrderCompletedEventData Fields

Example

{
  "type": "order.completed",
  "data": {
    "order_id": "ORD-2026-4521",
    "total": 149.99,
    "currency": "EUR",
    "emporiqa_session_id": "abc123-def456-ghi789",
    "items": [
      {"product_id": "product-42", "quantity": 2, "price": 49.99},
      {"product_id": "product-87", "quantity": 1, "price": 50.01}
    ]
  }
}

Getting the Session ID

The chat widget stores the session ID in the browser. Your store can retrieve it via the EmporiqaCartHandler or by reading the widget's session storage. Our platform plugins (WooCommerce, Drupal, Sylius) handle this automatically.

Dry Run (Test Connection)

Test your webhook integration without processing any data. Add ?dry_run=true to the webhook URL. The server runs the full validation pipeline (signature, rate limit, schema) but does not queue or store anything.

Request

POST https://emporiqa.com/webhooks/sync/YOUR_STORE_ID/?dry_run=true
Content-Type: application/json
X-Webhook-Signature: <HMAC-SHA256 signature>

{
  "type": "product.created",
  "data": { ... your normal product payload ... }
}

Response

{
  "status": "dry_run",
  "signature": "valid",
  "events_validated": 1,
  "events": [
    {
      "type": "product.created",
      "valid": true,
      "identification_number": "product-123",
      "sku": "JACKET-TRAIL",
      "languages_detected": ["de", "en"],
      "channels_detected": ["default"],
      "fields": {
        "names": true,
        "descriptions": true,
        "links": true,
        "categories": true,
        "attributes": true,
        "prices": true,
        "variation_attributes": true
      },
      "is_parent": true,
      "parent_sku": null,
      "warnings": []
    }
  ]
}

What It Checks

• Signature: HMAC-SHA256 verification (same as production)
• Rate limit: Counts against rate limits (same as production)
• Schema validation: Pydantic schema for each event type
• Field presence: Which translatable fields are populated
• Warnings: Data quality hints (missing descriptions, variation_attributes not matching attribute keys, empty prices)

Order Tracking API (Optional)

Emporiqa supports optional order tracking. Unlike webhooks (where your store pushes data to us), order tracking works in the opposite direction: when a customer asks about their order status in the chat, Emporiqa sends a request to your store's order tracking API endpoint.

How It Works

1. Configure your Order Tracking API URL in Store Settings > Integration
2. Customer asks "Where is my order #12345?" in the chat widget
3. Emporiqa sends a POST request to your endpoint with the order identifier
4. Your endpoint returns the order status (JSON, HTML, or plain text)
5. The salesperson formats the response and presents it to the customer

Request Format

Emporiqa sends a POST request to your configured URL:

POST https://yourstore.com/api/orders/track
Content-Type: application/json
X-Emporiqa-Signature: <HMAC-SHA256 signature>

{
  "order_identifier": "12345",
  "timestamp": 1707400000,
  "user_id": "customer-456",
  "verification_fields": {
    "email": "[email protected]",
    "phone_last_4": "1234"
  }
}

Request fields:

• order_identifier (string, always present): the order number or tracking ID provided by the customer
• timestamp (integer, always present): Unix timestamp of the request
• user_id (string, optional): the verified customer ID, extracted from the signed token passed when embedding the widget. This ID is cryptographically verified by Emporiqa before being forwarded, so you can trust it to restrict results to that customer's orders.
• verification_fields (object, optional): customer-provided verification data collected by the chat assistant before looking up the order. Only present if you have configured verification fields in Store Settings > Integration. The keys match the field names you defined, and the values are what the customer provided. Use these to verify the customer is authorized to view the order (e.g., check that the email matches the order record).

Authentication

Requests are signed with HMAC-SHA256 using the same connection secret configured in your store settings. The signature is included in the X-Emporiqa-Signature header. Verify this signature on your side to ensure the request is from Emporiqa.

Expected Response

Your endpoint should return one of the following:

• JSON (recommended): Return order data as JSON with Content-Type: application/json
• HTML: Return formatted HTML with Content-Type: text/html (HTML tags will be stripped)
• Plain text: Return plain text with order details
• 404: Return HTTP 404 if the order is not found