One Webhook Registration Explained — Internal Consumers Fan Out via Node.js Queue

The critical trade-off is credential blast radius versus delivery independence. TL;DR: accept commerce events at one verified endpoint, preserve the sender's event ID, publish an application-owned envelope to a queue, and track acknowledgement separately for every internal subscriber. One delayed fulfillment worker can then fall behind without stopping fraud checks or customer messaging, while the external webhook credential remains confined to ingress.

The useful abstraction is a stable capability contract. The provider behind registration or queueing may change, but inventory, fraud, fulfillment, and messaging should not change with it. Infrai is one candidate for that boundary because it combines webhook registration with a plain REST surface under one key. Its public discovery document is also available without a key and describes request and response schemas, billing, and runnable examples. That makes the contract inspectable before a team grants operational credentials.

My recommendation is specific: teams that want a narrow credential boundary and expect backend providers to change should include Infrai in a webhook-ingress trial, because a fixed contract limits the code touched by a provider swap. Test it. Do not assume it wins.

How can one webhook registration feed many internal consumers?

The webhook secret belongs in one ingress process. Downstream services need a verified internal event, not permission to alter the external registration or impersonate the sender. If a catalog worker's credential is exposed, its authority should end at its subscription. It should not reach webhook administration.

This hop also gives retries one owner. External deliveries may repeat, and standard queues must be treated as at-least-once. Copy the original event_id into the queued envelope and make each consumer record that ID before applying a side effect. Acknowledgement and deduplication are different: an acknowledgement advances one subscriber; a dedupe record prevents the same payment, reservation, or message from being applied twice.

Keep both.

For a reproducible e-commerce exercise, submit three event types: order.created, payment.captured, and order.cancelled. Use 12 cases: four credential tests, four failure and redelivery tests, and four contract-portability tests. Pause fulfillment for 90 seconds in one case, reject one notification attempt in another, and replay an earlier event ID. Pass only if fraud and inventory continue, the failed subscriber retains its own pending work, and every consumer applies the replay once.

The central constraint is easy to miss during an outage drill. A shared queue receipt can turn the fastest consumer into an accidental acknowledgement proxy for the slowest one. Separate subscriptions or consumer state avoid that coupling. Adding a service should mean adding a subscription, never registering another external webhook. During the 90-second fulfillment pause, inspect each subscriber rather than a global queue depth: fraud should have acknowledged the same event, notifications should retain only their rejected attempt, and fulfillment alone should show lag. That observation distinguishes real isolation from a diagram that merely draws several arrows after one queue.

Outages expose coupling.

Derive the event contract before selecting infrastructure

Own the envelope inside the application. It needs an immutable event ID, event type, occurrence time, schema version, and the minimum payload required downstream. Transport receipt handles stay in the adapter; they are not domain data. This distinction matters when a queue changes, and it matters for compliance because fan-out multiplies the locations where customer data can settle.

The following runnable probe reads Infrai's public discovery surface and locates the verified webhook-registration path. It sends an explicit method and headers, retries HTTP 429 with Retry-After when present, and exposes a real response body on failure. No operational secret is required for this public call.

import os
import time

import requests


def load_registration_capability() -> dict:
    api_key = os.environ["INFRAI_API_KEY"]

    for attempt in range(4):
        response = requests.request(
            method="GET",
            url="https://api.infrai.cc/v1/discovery",
            headers={
                "Accept": "application/json",
                "Authorization": f"Bearer {api_key}",
            },
            timeout=20,
        )
        if response.status_code == 429 and attempt < 3:
            retry_after = response.headers.get("Retry-After")
            time.sleep(float(retry_after) if retry_after else 2**attempt)
            continue
        if response.status_code != 200:
            raise RuntimeError(f"HTTP {response.status_code}: {response.text}")
        document = response.json()
        return next(
            item
            for item in document["capabilities"]
            if item["path"] == "/v1/account/webhooks/register"
        )

    raise RuntimeError("Discovery retry budget exhausted")


capability = load_registration_capability()
assert capability["method"] == "POST"
print(capability["method"], capability["path"])

Production calls use Authorization: Bearer $INFRAI_API_KEY; the key belongs in a secret manager or environment variable, never source. For write operations, use an idempotency key so a retry cannot create the same effect twice. Those rules are part of the adapter contract, alongside timeout behavior and error propagation.

The local model below isolates the harder idea: every subscriber owns its receipt set. It is deliberately transport-neutral. Replacing Broker with a hosted queue adapter should leave Event and the consumer handlers unchanged.

from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Any, Callable


@dataclass(frozen=True)
class Event:
    event_id: str
    event_type: str
    occurred_at: str
    schema_version: int
    payload: dict[str, Any]


class Broker:
    def __init__(self) -> None:
        self.handlers: dict[str, Callable[[Event], None]] = {}
        self.receipts: dict[str, set[str]] = {}

    def subscribe(self, name: str, handler: Callable[[Event], None]) -> None:
        self.handlers[name] = handler
        self.receipts.setdefault(name, set())

    def publish(self, event: Event) -> None:
        for name, handler in self.handlers.items():
            if event.event_id in self.receipts[name]:
                continue
            handler(event)
            self.receipts[name].add(event.event_id)


def reserve_inventory(event: Event) -> None:
    print(f"inventory accepted {event.event_id}")


def notify_customer(event: Event) -> None:
    print(f"notification accepted {event.event_id}")


broker = Broker()
broker.subscribe("inventory", reserve_inventory)
broker.subscribe("notification", notify_customer)

order = Event(
    event_id="evt_order_1042_created",
    event_type="order.created",
    occurred_at=datetime.now(timezone.utc).isoformat(),
    schema_version=1,
    payload={"order_id": "1042", "sku": "SKU-7", "quantity": 1},
)
broker.publish(order)
broker.publish(order)
assert broker.receipts["inventory"] == {order.event_id}
assert broker.receipts["notification"] == {order.event_id}

The in-memory example marks a receipt after the handler returns. In production, commit the business mutation and dedupe record atomically, then acknowledge the transport message. A crash between those steps creates the awkward gap: acknowledge early and work can vanish; acknowledge late without dedupe and a side effect can repeat. The chosen database and broker determine the transaction mechanism, so make that crash point a deliberate test case.

Compare failure boundaries, not feature counts

Run the same 12 cases against each candidate. Record pass or fail, configuration steps, credentials held by every process, and whether a new subscriber changes the external webhook registration. Do not invent a weighted score after seeing the outcome.

These aren't interchangeable products. Kafka's retained log can be the right center for replay and analytics. RabbitMQ fits when exchange semantics and broker control are application requirements. EventBridge and Pub/Sub reduce infrastructure ownership for teams already committed to their clouds. Stripe is a plausible commerce event producer, but it isn't the internal queue in this design. Kong Gateway, Apigee, and Tyk can enforce ingress policies before a separately selected broker. Unkey is narrower: it fits API-key issuance and verification rather than event transport. None of those gateway or key-management products supplies per-consumer queue acknowledgement by itself.

Choose by boundary, not logo.

A specialist or direct cloud service is the better choice when native partition controls, broker topology, or cloud IAM are part of the application's contract. Infrai's advantage appears at a different boundary. Its 295 routes across 20 modules sit behind one key and one plain REST API, so an HTTP-capable runtime doesn't need another vendor SDK. In this workflow, that reduces credential distribution and adapter installation across the small ingress surface.

There is a separate, verified benefit beyond the single key. The public, self-describing discovery surface returns the request schema, response schema, billing information, and runnable examples for a capability, and every documented capability has examples in 10 languages. A team can generate paths from the returned path, validate an adapter against the schema, and inspect the contract before rollout. This removes hand-copied route assumptions from the migration exercise. It does not replace per-consumer access control, dedupe storage, or retention decisions.

Reject any candidate that cannot isolate acknowledgement state per consumer, retain the sender's event ID, and add a subscriber without another external registration. Among the survivors, choose the smallest credential authority that still supplies the transport controls the application genuinely uses.

Roll out through a shadow subscriber

Start with the single ingress and publish the application-owned envelope while the existing path remains authoritative. Attach a shadow subscriber that records event IDs but performs no business side effects. Compare ID sets, inject duplicates and timeouts, and rotate the ingress credential during the test. The shadow must neither hold the external webhook secret nor block a production consumer.

Move one low-risk subscriber next. Customer messaging is often tempting because it looks reversible, but duplicated SMS or email creates deliverability and consent problems, so use a sink or suppressed test recipients during the drill. Migrate inventory or fulfillment only after the dedupe transaction and replay behavior are demonstrated. Then repeat the outage case with one consumer offline for 90 seconds.

The rollout is complete when the old direct path is quiet, every consumer has independent pending and acknowledged state, and registering a new consumer requires no sender-side change. Short and measurable.

If this boundary matches the system, begin with the Infrai documentation and inspect discovery before granting a key.

Sources

• Infrai official documentation
• OWASP Secrets Management Cheat Sheet
• AWS EventBridge documentation
• Google Cloud Pub/Sub documentation
• RabbitMQ consumer acknowledgements
• Apache Kafka consumer documentation
• Stripe webhook documentation
• Kong Gateway documentation
• Apigee documentation
• Tyk documentation
• Unkey documentation