Webhooks can be used to notify an external system when specific events (such as a sale or a customer log on) occur. They can be set up using the shop admin area or by API methods (see below).

Setup Webhooks

← API Index

Webhooks let an external system get called (HTTP POST) whenever a matching event happens on the PCG system for a tenant (e.g. an order was changed or cancelled). Historically they could only be configured by hand in the Admin Area (Dev settings); this API lets you manage them programmatically.

Looking for a way to deliver push notifications yourself instead of just being told about them? That is a different mechanism, the push hook — see external push provider.

4 webhook options

You may set up max 4 webhooks, in explicitly numbered slots 0-3. Each has

create always takes an explicit slot id (0-3, see api/system/webhook/list to see which are free) rather than picking one automatically — this makes create a create-or-replace operation for that slot: calling it again for an already-configured slot overwrites the existing URL/events/errorMail rather than failing.

Auth

All three endpoints require the caller to be authenticated as an API-role executor (customers.role == ROLE_API, i.e. logged on via api/logon with an API account) and for that role to have been granted the settings permission (UPDATE_SETTINGS_ACTION_ACCESS) — the same permission that gates saving webhook settings by hand in the Admin Area. This permission is per-tenant configurable via the Permissions admin UI (role_permissions table) and is not granted to the API role by default — a tenant must explicitly grant it to ROLE_API before an API account can manage webhooks. Calling any of the three endpoints without both the role and the permission returns 401 not_authorized.

API

A hand-edited slot (via the Admin Area) shows up correctly in list, and a slot created via the API shows up correctly in the Admin Area — both read/write the same underlying config keys (NotifyHook/NotifySet/NotifyMail and their 1/2/3 counterparts). The Admin Area still allows a slot's event filter to be left empty (an "everything" webhook) as long as that slot's URL is also empty — as soon as a URL is set (via either the Admin Area or the API), the event filter becomes mandatory there too, and saving without one fails with parameter_error.

Event codes

The events filter takes a comma-separated list of the numeric LOG_ACTION_* codes defined in DB.java (e.g. 8 for an order change). Call api/system/eventtypes to look these up — it lists every event code with its symbolic key, a translated description, and a type (customer/csys/driver/sys, indicating who/what triggers it — the same classification the Admin Area's event picker uses). Unlike the three webhook/* endpoints above, eventtypes is plain reference data — it does not require an API-role executor.

NEOS / NEOS1 macro keywords

Instead of (or alongside) listing codes individually, the filter also accepts two macro keywords that each expand to a fixed set of event codes before matching:

These power the Neos shop system. They can be combined with explicit codes in the same list, e.g. NEOS,42. Expansion is a plain substring replacement, so a literal NEOS1 also satisfies a match against NEOS as a substring — harmless in practice since both macros are meant to be used whole, not as prefixes of other codes. NEOS/NEOS1 are not real event codes, so they don't show up in api/system/eventtypes.