Webhook Events

This page lists the webhook events available for shop and marketplace integrations. Register webhooks during your app's installation migration to receive real-time notifications when data changes in the ERP.

Registration

Register webhooks using the Migrator:

await methods.registerWebhook(eventType, endpointPath);

Or using the ErpApi.webhook module directly:

await ErpApi.webhook.register(eventType, endpointPath);

Event Types

Article Events

Event	Description
article.update	An article's master data was modified

Payload:

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

Use case: Trigger product sync to push updated master data to the platform.

Scoped variant: You can scope article webhooks to a specific sales channel:

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

This filters events to only fire for articles assigned to the specified sales channel.

Stock Events

Event	Description
stock.update	Stock levels changed for an article

Payload:

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

Use case: Trigger stock sync to update inventory levels on the platform.

Note: Stock updates are frequent — every order, delivery, or adjustment triggers this event. Use deduplication in your queue.

Price Events

Event	Description
article-price.update	Prices changed for an article

Payload:

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

Use case: Trigger price sync to update product prices on the platform.

Sales Channel Events

Event	Description
sales_channel.create	A new sales channel was created for your app
sales_channel.delete	A sales channel was removed

Payload (sales_channel.create):

{
  "salesChannelId": "channel-uuid",
  "eventType": "sales_channel.create",
  "timestamp": "2026-01-15T10:30:00Z"
}

Use case: Initialize per-channel resources when a channel is created. Clean up resources when deleted.

Common initialization on channel create:

• Register channel-scoped webhooks

• Set up default configuration parameters

• Create channel-specific EAV groups

Document Events

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

Typical document events:

Event	Description
Document status transition	A document moved to a new status (e.g., order to delivery)

Use case: Trigger order status sync to send fulfillment updates to the platform.

Webhook Handler Pattern

All webhook handlers should follow the same pattern:

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

  // 2. Extract event data
  const { entityId, eventType } = req.body;

  // 3. Process asynchronously (queue or direct)
  try
  {
    await processEvent(eventType, entityId);
  }
  catch (error)
  {
    await log(`Webhook error: ${error.message}`, 'webhooks', 'ERROR');
  }
});

Deregistration

Remove webhooks when a sales channel is deleted or your app is uninstalled:

await ErpApi.webhook.deregister(eventType, endpointPath);

Best Practices

• Respond immediately — Send 200 OK before processing. The ERP has a timeout for webhook delivery.

• Process asynchronously — Add work items to a queue rather than processing inline.

• Deduplicate — The same entity may trigger multiple webhooks in a short window.

• Log arrivals — Log incoming webhooks for debugging.

• Handle gracefully — Never let a webhook handler crash. Catch and log errors.

• Clean up — Deregister webhooks when channels are deleted.