Webhooks

Vantemo webhooks notify your application in real-time when events happen in your store. Instead of polling the API for changes, register a webhook endpoint and we'll send you HTTP POST requests with event payloads.

How It Works

Register an endpoint — Provide a URL and choose which events to subscribe to
Receive events — When an event occurs, we POST a JSON payload to your URL
Verify the signature — Validate the HMAC signature to ensure authenticity
Respond with 2xx — Acknowledge receipt within 30 seconds

Event Types

Event	Description
`order.created`	A new order was placed
`order.updated`	An order's status or details changed
`order.cancelled`	An order was cancelled
`order.fulfilled`	An order was marked as shipped/delivered
`product.created`	A new product was created
`product.updated`	A product was modified
`product.deleted`	A product was archived or deleted
`customer.created`	A new customer account was created
`customer.updated`	A customer's profile was updated
`inventory.depleted`	A variant's stock reached zero
`checkout.completed`	A checkout session was successfully completed
`cart.abandoned`	A cart was abandoned (no checkout within threshold)

Payload Format

All webhook payloads follow the same envelope:

Webhook payload

{
  "id": "evt_1a2b3c4d",
  "type": "order.created",
  "createdAt": "2026-02-28T10:30:00.000Z",
  "data": {
    "id": "ord_9x8y7z",
    "status": "CONFIRMED",
    "total": 17160,
    "currency": "EUR",
    "customerEmail": "[email protected]"
  }
}

Signature Verification

Every webhook request includes an X-Vantemo-Signature header containing an HMAC-SHA256 signature. Verify it to ensure the payload wasn't tampered with:

Verify webhook signature

import crypto from 'node:crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf-8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post('/webhooks/vantemo', (req, res) => {
  const signature = req.headers['x-vantemo-signature'] as string;
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET!
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the event
  const { type, data } = req.body;
  console.log(`Received ${type}:`, data);

  res.status(200).json({ received: true });
});

Retry Policy

If your endpoint doesn't respond with a 2xx status code within 30 seconds, we retry with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours
6th retry	24 hours
7th retry	48 hours

After 7 failed attempts (approximately 72 hours), the webhook delivery is marked as permanently failed. You can view failed deliveries in the admin dashboard.

Best Practices

Respond quickly — Return 200 immediately and process the event asynchronously. Don't do heavy processing in the webhook handler.
Handle duplicates — Use the event id to deduplicate. Webhooks may be delivered more than once in rare cases.
Verify signatures — Always validate the HMAC signature before processing.
Use HTTPS — Webhook endpoints must use HTTPS in production.
Monitor failures — Check the admin dashboard for failed deliveries and fix endpoint issues promptly.

Creating a Webhook Endpoint

Via API

curl

curl -X POST https://your-shop.vantemo.com/v1/webhooks/endpoints \
  -H "Authorization: Bearer vt_sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.myapp.com/webhooks/vantemo",
    "enabledEvents": ["order.created", "inventory.depleted"]
  }'

Via Admin Dashboard

Navigate to Settings → Webhooks
Click Add Endpoint
Enter your URL and select event types
Copy the signing secret

Next Steps

API Reference — Webhook management endpoints
Authentication — Securing your integration

Webhooks Overview