FAQ

Frequently asked questions about webhooks.

How do I find out which events exist?

Ask the ERP:

GET /cmn/system/app-message-webhook/destinations

It lists every available queue with a description.

→ Webhooks Introduction

My webhook is registered but never fires.

Work through this in order:

1. Is the App active for this tenant? Events for inactive apps are discarded before any delivery record is created — so you won't even find a failed delivery.
2. Does that topic actually get emitted? The destinations list is generated and, for documents, contains every category/transition combination. Some are never emitted. Registering one succeeds and stays silent forever.
3. Are deliveries failing? Query system.queryAppMessageEntry and read recipients.response.
4. Are you answering in time? The timeout is 5 seconds.
5. Are you returning 401? See the App authentication FAQ.
6. Did you suppress it yourself? Check whether your own write set the suppression header.

Why does my webhook handler run twice?

Almost always a second registration you didn't intend. The identity of a subscription includes the full URL — so if the URL changed (a new domain, a different WEBHOOK_HOST in local development, a path convention change), the old subscription still exists and still fires.

The other cause is registering the same webhook from two places, for example a per-channel registration plus an always() step that also registers it.

How do I stop an infinite webhook loop?

If you react to article.update by writing back to the article, that write triggers the event again. Send this header on your write:

x-vario-suppress-own-webhooks: true

It suppresses only your own subscriptions; other apps still get the event.

Only the presence of the header is checked — not its value. Sending x-vario-suppress-own-webhooks: false still suppresses. Omit the header entirely when you want the event.

It also only works if VARIO can identify you as the caller, which is why the User-Agent must carry your app identifier.

How long may my handler take?

Under 5 seconds — so in practice: acknowledge first, then work. Return 200 immediately and continue processing asynchronously. Otherwise the delivery is recorded as failed and retried even though you handled it.

Are webhooks ordered? Delivered exactly once?

No and no. Delivery is at least once with no ordering guarantee, up to 3 attempts, after which it is abandoned permanently. Handlers must be idempotent.

Note that in-memory duplicate protection does not span processes — if you run several instances you need a shared guard.

Why does my cron webhook handler receive a string instead of an object?

Cron payloads can arrive double-encoded. Accept both:

const payload = typeof req.body === 'string' ? JSON.parse(req.body) : req.body;

Also remember a cron webhook needs two things: a subscription with owner APP, and a scheduled task with the same destination.