Webhooks

Webhooks are the primary mechanism for VARIO ERP to notify your app about data changes in real time. When an article is updated, stock levels change, or an order status transitions, the ERP sends an HTTP POST request to your app's registered webhook endpoint.

Registering Webhooks

Register webhooks during your app's installation migration using the Migrator:

const { Migrator } = require('@vario-software/vario-app-framework-backend/utils/migrator');

const migrator = new Migrator('install');

await migrator.setMigration('register-webhooks', async (methods) =>
{
  // Article master data changes
  await methods.registerWebhook(
    'article.update',
    '/api/webhooks/article-update'
  );

  // Stock level changes
  await methods.registerWebhook(
    'stock.update',
    '/api/webhooks/stock-update'
  );

  // Price changes
  await methods.registerWebhook(
    'article-price.update',
    '/api/webhooks/price-update'
  );

  // Sales channel lifecycle
  await methods.registerWebhook(
    'sales_channel.create',
    '/api/webhooks/sales-channel-create'
  );

  await methods.registerWebhook(
    'sales_channel.delete',
    '/api/webhooks/sales-channel-delete'
  );
});

The first argument is the event type — the kind of ERP event you want to listen for. The second argument is the endpoint path on your app where the ERP should send the notification.

Webhook URLs are relative to your app's root URL. If your rootUrl is https://app.example.com/, the webhook for article.update will be sent to https://app.example.com/api/webhooks/article-update.

Handling Webhooks

The most important rule for webhook handlers: respond immediately, process later.

app.apiServer.post('/webhooks/article-update', async (req, res) =>
{
  // 1. Respond immediately with 200 OK
  res.status(200).send({ success: true });

  // 2. Process asynchronously
  try
  {
    const { entityId } = req.body;
    await addToQueue('article.sync', entityId);
  }
  catch (error)
  {
    await log(`Webhook processing error: ${error.message}`, 'webhooks', 'ERROR');
  }
});

Why Respond Immediately?

• VARIO ERP has a timeout for webhook delivery. If your handler doesn't respond in time, the ERP may retry the webhook, creating duplicate work.

• Processing the sync operation (fetching data, transforming, pushing to platform) can take seconds or minutes — far too long for a synchronous HTTP response.

• By responding immediately and queuing the work, you decouple the webhook notification from the actual processing.

Common Webhook Events

Article Events

Event	When It Fires
article.update	An article's master data is modified (name, description, attributes, etc.)

Use this to trigger product sync to your platform. The webhook payload includes the article ID, which you can use to fetch the full article data via VQL or the REST API.

Stock Events

Event	When It Fires
stock.update	Stock levels change for any article

Stock changes happen frequently — every order, delivery, or manual adjustment triggers this event. Consider deduplication in your queue to avoid processing the same article multiple times in quick succession.

Price Events

Event	When It Fires
article-price.update	Prices change for any article

This covers base prices, customer group prices, and price tiers.

Sales Channel Events

Event	When It Fires
sales_channel.create	A new sales channel is created for your app
sales_channel.delete	A sales channel is removed

These events let you initialize or clean up per-channel resources. For example, when a new sales channel is created, you might register additional webhooks scoped to that channel or set up default configuration.

Document Events

Document events relate to sales orders, delivery notes, invoices, and other business documents.

Webhook Payload

Webhook payloads are JSON objects sent as the request body. The exact structure depends on the event type, but typically includes:

{
  "entityId": "uuid-of-the-changed-entity",
  "eventType": "article.update",
  "timestamp": "2026-01-15T10:30:00Z"
}

For the full payload reference by event type, see Webhook Events Reference.

Scoping Webhooks to Sales Channels

For some events, you can scope the webhook to a specific sales channel by including the channel ID in the event filter:

await methods.registerWebhook(
  `article(sales-channel-id=${salesChannelId}).update`,
  `/api/webhooks/article-update?salesChannel=${salesChannelId}`
);

This ensures your webhook only fires for articles assigned to that specific sales channel, reducing noise.

Deregistering Webhooks

When a sales channel is deleted or your app is uninstalled, clean up your webhooks:

const ErpApi = require('@vario-software/vario-app-framework-backend/api/ErpApi');

await ErpApi.webhook.deregister(
  'article.update',
  '/api/webhooks/article-update'
);

If you registered channel-scoped webhooks, make sure to deregister them when the channel is deleted. Otherwise, the ERP will continue sending webhooks to endpoints that no longer expect them.

Best Practices

• Always respond 200 immediately — Never do heavy processing in the webhook handler

• Queue, don't process — Add work items to a queue and process them asynchronously

• Deduplicate — If the same entity is updated rapidly, avoid queuing redundant work

• Log webhook arrivals — Helpful for debugging sync issues

• Handle errors gracefully — A failing queue operation shouldn't cause the webhook handler to throw