# RFC 0196: `callbackUrl` is refused or delivered under the egress guard, and an embedded IPv4 address is judged as IPv4

> Source: https://openwop.dev/rfcs/0196-callbackurl-and-embedded-ipv4-egress.html · OpenWOP, the open-source protocol for multi-agent workflow orchestration. CC BY 4.0.

| Field             | Value                                                           |
| ----------------- | --------------------------------------------------------------- |
| **RFC**           | 0196                                                            |
| **Title**         | `callbackUrl` is refused or delivered under the egress guard, and an embedded IPv4 address is judged as IPv4 |
| **Status**        | `Accepted`                                                      |
| **Author(s)**     | David Tufts (@davidscotttufts)                                  |
| **Created**       | 2026-09-21                                                      |
| **Updated**       | 2026-09-21 (filed `Draft`; **the public comment window runs in full, to 2026-09-28** — RFC 0147 §A.6: this RFC affects external effects, so bootstrap waiver language MUST NOT shorten its window) · 2026-09-21 (later) — `Draft → Active`; **comment window waived** by the steward on 2026-09-21 — an explicit **steward override of RFC 0147 §A.6**, which forbids bootstrap waiver language from shortening the window for an RFC of this risk class; it is outside the `MAINTAINERS.md` waiver grant, recorded there as an override, not as a routine waiver (this RFC affects external effects). · 2026-09-22 — **`Active → Accepted`, provisional pending RFC 0156 §B retrospective review** (it went `Active` under a waived window; the register row stays `not-reviewed`). Evidence tier: tier-2 — MyndHyve `workflow-runtime`, a production host (steward-affiliated), single witness for §A.3: it advertises `interrupt.callbackDelivery: true` (in its signed discovery document and live), and on the published suite 2.35.0 (build `commit:ace23a7e`, verified against its live `/readiness`; nothing relaxed; both profiles certified) `0196.callback-url-guarded` is `executed-pass` — loopback, cloud metadata and hex-mapped loopback `callbackUrl`s each refused `400 validation_error`, `details.field: callbackUrl`. §B.5 is witnessed by `0171.webhook-egress-refused` on both committed bundles. |
| **Affects**       | `spec/v2/core/runs.md` (`createRun.callbackUrl`), `spec/v2/core/interrupt.md`, `spec/v2/core/webhooks.md` §Egress, the `interrupt` family's facets, `spec/v1/rest-endpoints.md` (a pointer only), conformance |
| **Compatibility** | `additive` per `COMPATIBILITY.md`                               |
| **Supersedes**    | —                                                               |
| **Superseded by** | —                                                               |

## Summary

`createRun.callbackUrl` is a member of the closed create body at both majors and specified nowhere; `interrupt.md`, which the OpenAPI description points to, never mentions it. Measured on three hosts, it gets three behaviours: one accepts it and ignores it, one refuses it, and one delivers a vendor-shaped approval request to it — with, until 2026-09-21, no egress guard on a request to a URL the caller chose. Separately, the webhook egress guard of the same hosts judged an IPv4-mapped IPv6 address by its dotted spelling, which a URL parser never emits, so loopback, cloud metadata and RFC 1918 passed. This RFC makes `callbackUrl`'s delivery discoverable, binds a delivering host to the webhook egress guard, and states that an address embedding IPv4 is judged by the IPv4 it embeds.

## Motivation

**`callbackUrl` (openwop#1449).** `api/openapi.yaml` and `api/v2/openapi.yaml` describe it as "Signed-token HITL callback URL (see `interrupt.md`)"; `runs.md` lists it among the closed `createRun` members; `interrupt.md` does not contain the word "callback". v2 mints signed resolve tokens (`interrupt.md` §Tokens) and specifies no channel by which a token reaches its holder — `callbackUrl` is that missing channel. Measured 2026-09-21:

| host | behaviour |
| --- | --- |
| v2 reference host | `201`, member not stored, nothing delivered |
| openwop-app | `400 validation_error`, `details.field: callbackUrl` |
| MyndHyve | on an approval interrupt, POSTs a signed approval request to it; now guarded (it was not) |

A client cannot tell these apart, and an outbound request to a caller-chosen URL is the surface `webhooks.md` §Egress exists for.

**Embedded IPv4.** `webhooks.md` §Egress requires refusing loopback, link-local, RFC 1918 and metadata destinations. The WHATWG URL parser normalises `https://[::ffff:127.0.0.1]/` to hostname `::ffff:7f00:1`. A guard that recognised only the dotted mapped form accepted it — measured on the steward's reference host at registration and at delivery (two POSTs reached a real loopback listener), and present in two other hosts' guards. Suite 2.35.0 already adds three hex-mapped probes to `0171.webhook-egress-refused` as enforcement of the existing MUST; this RFC writes the rule down and extends it to the other standard translation forms.

## Proposal

### §A `callbackUrl`

1. The `interrupt` family gains an optional boolean facet `interrupt.callbackDelivery`. A host advertises `true` only if it delivers to `callbackUrl`.
2. A host that does not advertise `interrupt.callbackDelivery: true` SHOULD refuse a `createRun` carrying `callbackUrl` with `400 validation_error` and `details.field: "callbackUrl"`. It MUST NOT advertise delivery it does not perform.
3. A host that advertises `interrupt.callbackDelivery: true` MUST apply the `webhooks.md` §Egress guard to `callbackUrl`: at `createRun` it MUST refuse, with `400 validation_error` and `details.field: "callbackUrl"`, a URL the registration guard would refuse; at delivery it MUST re-validate every resolved address and MUST NOT follow a redirect.
4. The delivery's payload, timing and signing are host-defined in this revision; a later RFC may specify an interoperable shape. `interrupt.md` says so, and the OpenAPI description of `callbackUrl` points there.

### §B An address that embeds IPv4

5. An IPv6 address in the IPv4-mapped form (`::ffff:0:0/96`) MUST be judged, everywhere `webhooks.md` §Egress applies, by the IPv4 address it embeds — whatever its spelling. (It is that IPv4 address; this states the existing rule.)
6. An IPv6 address that embeds IPv4 in another standard translation form — IPv4-compatible (`::/96`, other than `::` and `::1`), NAT64 (`64:ff9b::/96`) and 6to4 (`2002::/16`) — SHOULD be judged by the IPv4 address it embeds. A host SHOULD NOT deny those prefixes wholesale: an IPv6-only host behind DNS64 is legitimately handed `64:ff9b::<public IPv4>` for a public destination.
7. A host SHOULD refuse every destination that the IANA IPv4 and IPv6 Special-Purpose Address Registries mark not globally reachable, in addition to the classes `webhooks.md` §Egress names.

**Positive examples.** `https://[64:ff9b::5db8:d822]/` (NAT64 of a public address) is accepted; a `callbackUrl` of `https://hooks.example.com/approve` is accepted by a host advertising delivery.

**Negative examples.** `https://[::ffff:7f00:1]/`, `https://[::ffff:a9fe:a9fe]/` (cloud metadata) and `https://[64:ff9b::7f00:1]/` are refused; a host advertising `interrupt.callbackDelivery: true` answering `201` to `callbackUrl: https://[::ffff:7f00:1]/hook` violates §A.3.

## Compatibility

**Additive.** §A.1 is a new optional facet; a host that does not advertise it is bound only by SHOULDs (§A.2) and by not claiming delivery it does not perform. §A.3 binds only an advertising host. §B.5 states an existing obligation (a mapped address *is* its IPv4 address); §B.6–§B.7 are SHOULDs. No field, endpoint or error meaning changes, and no `MUST` is relaxed. `callbackUrl` stays in the create body at both majors.

## Conformance

Lands when this RFC is `Active` (`check-rfc-status-coherence.mjs` rule 7).

- The existing `0171.webhook-egress-refused` probes already cover §B.5 (suite 2.35.0); a NAT64 loopback probe joins it as a SHOULD-level observation recorded in the row's detail, never as a failure.
- A new major-2 leg, gated on `interrupt.callbackDelivery: true`: `createRun` with `callbackUrl` naming loopback, cloud metadata and an IPv4-mapped loopback MUST each answer `400 validation_error` with `details.field: "callbackUrl"`. `inapplicable` where the facet is absent.

### Falsifiability — one row per normative requirement

| Requirement | Observable — what an outside party sees | Who can cause the condition | Verdict |
| --- | --- | --- | --- |
| §A.1 / §A.2 advertisement is honest | nothing — whether a host delivers is visible only to a receiver the host chooses to call | — | unwitnessable — delivery happens only on an interrupt, to a URL the suite would have to expose publicly; the advertising half is checked by §A.3 on hosts that advertise |
| §A.3 a delivering host guards `callbackUrl` at create time | `400 validation_error`, `details.field: "callbackUrl"`, for a loopback / metadata / mapped-loopback `callbackUrl` | the suite, unaided, on a host advertising `interrupt.callbackDelivery: true` | witnessable — gated on the `interrupt.callbackDelivery` facet |
| §A.3 delivery-time re-validation, no redirects | nothing — a host's resolver and connector are not on the wire | — | unwitnessable — same reason as the reference-impl invariant `webhook-delivery-egress-revalidation` |
| §B.5 mapped IPv4 judged as IPv4 | `400 webhook_url_rejected` for `https://[::ffff:7f00:1]/` and siblings | the suite, unaided, gated on `webhooks` (`0171.webhook-egress-refused`) | witnessable — gated on the `webhooks` family |

## Alternatives considered

- **Remove `callbackUrl` at major 2.** v2.x is additive-only; one production host uses it.
- **Require every non-advertising host to refuse it.** Makes the reference host's current `201` a violation — a new MUST on existing behaviour, which `COMPATIBILITY.md` §3 allows only as a safety fix with a 90-day window; a non-delivering host has no egress exposure to fix.
- **Specify the delivery shape now.** No second host delivers; a shape specified from one vendor's payload would be that vendor's shape. The likely shape — an `interrupt.requested` delivery under the webhook rules carrying `{ token, expiresAt }`, authenticated by the receiver calling `GET /interrupts/{token}` — is recorded here for the later RFC.
- **Deny NAT64 and 6to4 wholesale.** Breaks IPv6-only hosts behind DNS64.

## Unresolved questions

1. The interoperable delivery shape (§A.4) — deferred until a second host delivers.
2. Whether §B.6 should become a MUST once hosts report its cost.

## Implementation notes (non-normative)

The v2 reference host judges egress by address since openwop-examples#67 (bytes, embedded IPv4 unmapped, only globally reachable allowed). It accepts and ignores `callbackUrl` today and will refuse it (§A.2) when this RFC is `Active`. MyndHyve guards `callbackUrl` at create time and at delivery (its #460); openwop-app refuses it.

## Acceptance criteria

- [x] `Active` — 2026-09-21, by steward override of RFC 0147 §A.6 (the window was waived, not run; see `Updated`).
- [x] Spec text merged: `runs.md`, `interrupt.md` §Callback delivery, `webhooks.md` §Egress, the `interrupt.callbackDelivery` facet (2026-09-21, 2.35.0).
- [x] The §A.3 leg ships in a published suite (2.35.0, 2026-09-22).
- [x] A committed host bundle from a host advertising `interrupt.callbackDelivery: true` carries the §A.3 row at `executed-pass` — MyndHyve (`evidence/v2-host-bundles/myndhyve.json`, suite 2.35.0).

## References

- openwop#1449; RFC 0147 §A.6; `spec/v2/core/webhooks.md` §Egress; `spec/v2/core/interrupt.md` §Tokens; IANA IPv4 / IPv6 Special-Purpose Address Registries; RFC 6052 (NAT64), RFC 3056 (6to4), RFC 4291 §2.5.5 (IPv4-mapped / -compatible).
