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
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
- a target URL (required to be considered "configured")
- a required event filter: a comma-separated list of event/action codes (see Event codes below) — there is no "fire on every event" option via this API.
- an optional error-notification email: comma-separated address(es) that get mailed if webhook calling keeps failing
- an error count: how many consecutive deliveries have failed since the URL was last set; reset automatically whenever the URL is changed
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
api/system/webhook/create— create or replace the webhook in the given slot. Parameters:id(required, 0-3),url(required),events(required, comma-separated event codes — see Event codes),errorMail(optional, comma-separated emails). Returns the slotid. Fails withparameter_errorifidis missing/out of range, or a value doesn't validate (e.g.url/eventsmissing, invalid URL scheme).api/system/webhook/list— lists all 4 slots with their current configuration (id,configured,url,events,errorMail,errorCount).api/system/webhook/drop— clears one slot. Parameter:id(0-3, required). Idempotent: dropping an already-empty slot still returnsdropped.
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:
NEOS→54,5000,97,2041,3001,2040,2175NEOS1→2110,8,2082,53,61
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.