External Actions Queue handler execution; ADR-0011 amended and the queue contract bumped to v1.2.0, producer domains expose a Platform-callable /api/external-actions/execute endpoint
Why
The External Actions Queue producer SDK shipped as @sguild/external-actions@1.0.0 (2026-05-22-platform-external-actions-producer-sdk-distribution), so a producing domain can enqueue an outbound action today. But enqueue is only half of an action's life: the queue runner then has to invoke the domain's handler, the code that performs the actual outbound effect. ADR-0011 §7.4 and §"Consequences" described handlers as "registered with Platform's runner at boot," which only works if the handler and the runner share a process. They do not. The runner is a Platform-side process; a producing domain's handler is provider-specific code in that domain's deploy. This memo announces how that gap is now closed.
What
ADR-0011 carries a new "Amendment 2026-05-22: handler execution topology." Platform's runner invokes a producing domain's handler over an HMAC-signed HTTP callback, the outbound-side mirror of the dispatcher's webhook fanout. The runner resolves the owning domain from the action's producer column, POSTs the action to that domain's handler-execution endpoint, and writes the attempt from the returned classification. Per-domain endpoint URLs and secrets ride the same env-config shape as the dispatcher fanout's consumer configuration.
The external-actions queue contract is bumped to v1.2.0 to spec this. A new §7.5 defines the handler-execution endpoint: each producing domain exposes POST /api/external-actions/execute, verifies an X-External-Actions-Signature HMAC, runs its in-process handler, and returns the HandlerResult as JSON. §7.4 is rewritten to correct the cross-process registration framing: handlers register in the producing domain's own process, not on Platform's runner.
The HTTP-callback direction was chosen over a per-domain runner, which would fragment the single-runner design ADR-0011 committed to, and over vendoring handler code into Platform's runner, which would couple Platform to every provider SDK. The amendment carries that reasoning in full.
Asks
To Delivery, Revenue, and Sales: this is the external-actions queue contract v1.2.0 announcement. Ack on this thread within the soft response window. The new obligation is one endpoint per producing domain: a Platform-callable POST /api/external-actions/execute that verifies the HMAC and runs your registered handler, per contract §7.5. Build it as roadmap work when you take on external-actions handlers; it is not needed to enqueue, only for the runner to execute. Delivery's is first in line: the NPS V1 survey send (2026-05-22-coaching-nps-program-v1-spec) does not fire end to end until Delivery's execute endpoint and its SMS-send-class handler are live. Until a domain stands up its endpoint, the runner treats it as a non-failing skip (the EXTERNAL_ACTIONS_DEV_STUB path), so a half-provisioned org does not accumulate dead-letters.
Platform commits to the runner-side HTTP-callback path; that commitment is on this memo's frontmatter. Platform's own handlers run in Platform's process, so Platform needs no execute endpoint.
References
- ADR-0011 and its "Amendment 2026-05-22: handler execution topology":
adrs/ADR-0011-external-actions-at-platform.md - External Actions Queue contract v1.2.0, §7.4 and §7.5:
contracts/external-actions/README.md - The producer SDK distribution decision and v1.1.0 bump:
2026-05-22-platform-external-actions-producer-sdk-distribution - Dispatcher webhook fanout, the inbound-side precedent: ADR-0009
- NPS V1 program spec, the first producer needing handler execution:
2026-05-22-coaching-nps-program-v1-spec