Open Connector
Receive Connector events

Receive Connector events

Deploy a signed event receiver, store verified events durably, test a subscription, and enable delivery for an approved connection.

Run a receiver that verifies Connector signatures and stores each event in a durable inbox before returning 204. Use the inbox as input to your catalog or ticket worker; keep native product changes behind their existing approvals.

Before you begin

You need the following service and deployment configuration:

  • An active custom integration connection grants the categories corresponding to the requested event types.
  • A worker key has subscriptions:read, subscriptions:write, and operations:read.
  • The receiver runs on Linux with Node.js 20 or later and a persistent local filesystem that supports hard links and directory synchronization.
  • A public HTTPS reverse proxy forwards /connector/events to the receiver's 127.0.0.1:8080 listener without changing body bytes.
  • The persistent inbox directory is provisioned for the receiver account and has a retention and downstream processing policy.

Create a disabled subscription

  1. In Console, open Organization → Connector → Connections → Connection → Events. Select Create subscription.
  2. Enter the public HTTPS receiver URL. Select the event types required for the consumer, such as inventory.upserted and inventory.removed.
  3. Select Create subscription. Record the subscription ID and save the one-time signing secret and its version ID in the receiver's secret manager.
  4. Confirm Disabled and Not tested. For API automation, use Create a subscription.

If URL validation fails, inspect public DNS, HTTPS trust, and the destination address. Private addresses, URL credentials, and redirects are rejected.

Start the receiver

Configure these variables for the receiver process:

VariableValue
CONNECTOR_ORGANIZATION_IDExpected owning organization ID
CONNECTOR_CONNECTION_IDExpected connection ID
CONNECTOR_WEBHOOK_SECRETSJSON object mapping accepted secret version IDs to base64 secrets
CONNECTOR_EVENT_TYPESComma-separated selected types, without spaces; tests are accepted separately
CONNECTOR_INBOX_DIRProvisioned persistent inbox path; defaults to ./connector-inbox

  1. Download , a Node.js source file, to the Linux receiver host. Open a terminal in its directory.

  2. Start the process with its configured environment:

    Shell
    node webhook-receiver.mjs

    The output is similar to the following:

    Plain text
    Receiver listening on 127.0.0.1:8080

  3. In the HTTPS proxy, confirm that the saved public URL reaches that listener. Preserve all Connector-* headers and enforce the 1 MiB request-body limit.

The receiver implements the signature contract. It writes a complete temporary file, synchronizes it, and links it into the inbox under a hash of the event identity. A repeated event reaches the same file and receives 204 without creating another inbox entry. Storage failures return 503.

Test and enable delivery

  1. In Connection → Events → Subscription, select Test delivery. The subscription remains disabled while the signed synthetic test runs.
  2. In Deliveries, open the test. Confirm Delivered, its event and delivery IDs, and the signing-secret version expected by the receiver.
  3. On the receiver host, open the corresponding inbox entry. Confirm test: true, type subscription.test, and the expected organization and connection IDs.
  4. In Subscription, select Enable delivery. Confirm Enabled and then inspect the next permitted source event in both Deliveries and the inbox.

If the test returns 401, compare clock health, raw body handling, secret version, and expected IDs. If it returns 503, correct inbox permissions or storage health before retrying. The API equivalents are Test a subscription and Update a subscription.

Process the inbox

Keep admitted event files until the downstream worker has completed its own transaction and deduplication record. This example has no automatic deletion or downstream consumer. Ignore synthetic tests when performing business work.

For an inventory event, schedule a fresh source read or catalog synchronization. For a security summary, follow the source finding and mapped resource. Use native Infra or Guard APIs for changes, with their required permissions and approvals.

An event file proves durable admission on this host. It does not establish that a ticket update or product operation succeeded. For transport recovery, use Replay a failed delivery.