Webhook operations

This page collects the operator-side commands for the webhook subsystem: Mongo index migration, config backfill from existing live registrations, reconciliation from schema, and a diagnostic CLI that bypasses the API gateway.

For the user-facing flow (Subscribe, Unsubscribe, orphan banner) see Patterns: Webhooks. For the canvas mechanics see Building nodes: Event nodes.

Mongo index migration #

After deploying a new bundle that introduced or changed the WebhookConfig document, refresh the Mongo indexes:

php bin/console mongodb:index:update

This adds the unique (topologyName, nodeName, application, user, sdk) index plus the secondary topologyName and (application, user) lookup indexes used by the list views.

Idempotent — re-running the command on an up-to-date schema does nothing.

Backfill configs from live webhooks #

If you upgrade an instance that already has live Webhook registrations from the legacy flow, the new WebhookConfig collection starts empty and the topology detail view shows blank Off badges even though events keep arriving. Backfill the configs from the existing live records:

php bin/console webhook:seed-configs --dry-run   # preview what would be created
php bin/console webhook:seed-configs             # apply

The command iterates every Webhook document, derives a WebhookConfig from its (application, user, sdk, topology, node, name) tuple, and persists it only if no equivalent config exists.

Fully idempotent — re-runs print how many records were created vs. skipped, never duplicates anything.

After running it, the topology detail view picks up the backfilled configs immediately and flips the relevant webhook nodes to the Subscribed badge.

Reconcile configs from schema #

Configs are now created lazily on the first Subscribe, so most operators will not need this command. It remains useful for two scenarios:

php bin/console webhook:reconcile-configs                       # all topologies
php bin/console webhook:reconcile-configs --topology=order-sync # one topology

1. Migrating from the old eager-upsert era when the schema-save hook used to auto-create configs and you want to confirm coverage of historic records.
2. Bootstrapping a hand-imported schema where you want pre-populated configs (with enabled = false) so a cascade-on-enable can pick them up without a manual round-trip through the UI.

The command re-runs WebhookConfigManager::upsertFromNode for every TypeEnum::WEBHOOK node currently in the schema.

Diagnostic CLI — single config #

The diagnostic CLI bypasses HTTP authentication and exercises WebhookConfigManager directly. It is the fastest way to reproduce "UI says ok but nothing happened" reports — errors propagate to the console with full stack traces.

php bin/console webhook:subscribe-config <topology> <node> {list|subscribe|unsubscribe}

Examples:

php bin/console webhook:subscribe-config order-sync ignored list

php bin/console webhook:subscribe-config order-sync webhook-test.ping subscribe
php bin/console webhook:subscribe-config order-sync webhook-test.ping unsubscribe

The list form ignores its second argument (the node name) and prints registered, webhookId, enabled, and orphan for every config attached to the topology.

Orphan cleanup workflow #

A WebhookConfig is flagged as orphan when its nodeName is not present in the currently enabled version of the topology — usually because the topology was republished and the webhook node was renamed or removed, or because a manual schema import dropped the node.

The user-facing path is the yellow banner in the topology detail with a one-click Cleanup action, which best-effort unsubscribes the live registration and removes the config record.

For operators investigating a stack of orphans across multiple topologies:

1. List configs for the affected topology with webhook:subscribe-config <topology> <ignored> list.
2. Confirm the live registration with the upstream provider's admin console (sometimes the upstream service has its own ghost record).
3. From the UI, click Cleanup in the orphan banner — that path is the same idempotent code as the webhook:subscribe-config <topology> <node> unsubscribe CLI plus the config delete.

See also #

• Patterns: Webhooks — user-facing flow
• Building nodes: Event nodes — canvas UI
• Reference: Node.js / AWebhookApplication
• Reference: Node.js / WebhookSubscription