Subscriptions and Filters#

The public create and edit contract uses subscriptions[] exclusively. Do not send legacy event aliases, transport route names, or organization IDs.

tsinterface WebhookSubscription {
  eventType: string;
  version: number;
  filters?: Record<string, string[]>;
}

Event catalog#

GET /v1/webhooks/event-catalog returns the supported IDs and their:

• group, scope, and expected volume
• defaultVersion and versioned CloudEvent wireType
• filtersSchema, including fixed options and custom-value support
• schemaUrl, docsUrl, and localization keys

Build selectors from this response instead of copying a static event list. The Portal uses the same catalog.

Filter semantics#

• Omit filters, or send an empty object, to match all values.
• Values within one filter key use OR semantics.
• Different filter keys use AND semantics.
• Unknown keys, unknown fixed options, empty arrays, duplicate subscriptions, and unsupported versions are rejected.
• accountRefs must belong to the caller's active organization. Artery derives organization ownership from authentication; clients never submit orgId.

Common keys include providers, brokers, universalIds, accountRefs, directions, states, finalities, closeReasons, kinds, and phases. Only use keys declared by the selected catalog entry.

Round trip#

Create, list, detail, and edit responses return the same logical subscription shape. A client should be able to deserialize the response and render the same checked Event Types, versions, and filters without reverse-mapping an internal identifier.

See the Webhook API reference for request and response schemas.