E-commerce

Webhooks

Webhooks allow your system to receive real-time HTTP notifications when events happen in your store. Use them to sync inventory to external databases, trigger shipping labels, or send custom order confirmation emails.

The Webhook Workflow

  1. 1Registration: Add your server endpoint URL in the Dashboard > Developers > Webhooks section.
  2. 2Secure Secret: Copy the whsec_... signing secret. You'll need this to verify requests.
  3. 3Receive Event: Elective Commerce sends a POST request with a JSON payload to your server.
  4. 4Verify & Process: Validate the X-E-Commerce-Signature header and return a 200 OK.

Supported Events

You can subscribe to all events using the wildcard * or select specific triggers:

Event NameDescription
order.createdFired immediately when a checkout intent is successfully verified.
order.paidFired when payment is confirmed by the gateway (Stripe/Paystack).
order.fulfilledFired when an order is marked as fulfilled in the dashboard.
customer.createdFired when a new customer registers an account.

Payload Structure

Every webhook request follows a standard envelope format, allowing you to parse the event type reliably.

JSON Payload

{
  "id": "evt_01j7x...",
  "event": "order.paid",
  "created_at": 1736611200,
  "data": {
    "orderId": "8f3e...",
    "total": 5500,
    "currency": "USD",
    "customer_id": "cust_123"
  }
}

Implementation: Verify Signatures

To prevent Man-in-the-Middle attacks, you must verify that the incoming request was signed by Elective Commerce. We use HMAC-SHA256 hex signatures.

Node.js (Native Crypto)

JavaScript

const crypto = require('crypto');

// This logic should live in your Webhook route handler
const handleWebhook = async (req, res) => {
  const signature = req.headers['x-e-commerce-signature'];
  const secret = 'whsec_YOUR_SECRET_FROM_DASHBOARD';
  const payload = JSON.stringify(req.body);

  // 1. Generate the expected signature
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');

  // 2. Compare safely using timingSafeEqual if possible, 
  // or a standard string comparison for simple use-cases.
  if (signature === digest) {
    console.log('Verified:', req.body.event);
    
    // Process your logic here...
    
    res.status(200).send('OK');
  } else {
    console.error('Signature mismatch');
    res.status(401).send('Unauthorized');
  }
};

Configure in Dashboard

Navigate to Developers > Webhooks inside your store workspace. Click Add Endpoint and provide your public server URL. Ensure your server is capable of receiving POST requests with JSON bodies.