Wiring External Webhooks

Wiring external webhooks to HTTP signals

A provider: http signal in workspace.yml exposes a URL. To make something fire it you register the URL with the upstream system (any service that can POST JSON). Friday's webhook-tunnel is the public entry point — it forwards the request body to atlasd's signal endpoint.

The tunnel does one thing: take the POST body and hand it to the workspace's signal. No HMAC verification, no event filtering, no field extraction. Every webhook from every upstream uses the same URL shape and the same body-passthrough semantics.

URL pattern — always /hook/raw/ on the PUBLIC tunnel host

Copy code
https://<public-tunnel-url>/hook/raw/<workspaceId>/<signalId>

• <public-tunnel-url> is the cloudflared trycloudflare URL — fetch it live from /status (next section). It rotates on tunnel restart.
• <workspaceId> is the runtime id (e.g. light_papaya, not the friendly name).
• <signalId> is the signal's key in workspace.yml.

Never give an external service a URL of the form <friday-host>/api/workspaces/<wsId>/signals/<signalId> — that path is atlasd's internal direct route. It is not exposed through cloudflared, the upstream cannot reach it from the public internet, and recommending it is the original foot-gun that motivated this skill. If you cannot reach /status from your environment to fetch the real tunnel URL (run_code does not always have network access to the local tunnel), STOP and ask the user to run the /status curl themselves and paste the URL back — do not synthesize a host or fall back to the /api/workspaces/... path.

Get the tunnel URL in one call

The local webhook-tunnel listens on whatever $EXTERNAL_TUNNEL_URL points at (the launcher / playground exports this; default is https://localhost:9090 on bare-dev rigs). Always read it from the env — do not hardcode the port, it differs per rig:

bashCopy code
curl -sk "${EXTERNAL_TUNNEL_URL:-https://localhost:9090}/status" | jq
# → { "url": "https://...trycloudflare.com",
#     "providers": ["raw"], "pattern": "/hook/raw/{workspaceId}/{signalId}", ... }

If that returns empty (exit 0 but no body), the port is wrong for this rig. Run echo "$EXTERNAL_TUNNEL_URL" to confirm what the launcher set, or ps auxww | grep cloudflared to read the --url flag the tunnel was started with — that's the actual local port. Do NOT silently move on; the URL is the whole point of this skill.

/status is the single source of truth — it shows the current trycloudflare URL (rotates on tunnel restart) and confirms the tunnel is up. Run it FIRST when something's wrong before guessing.

Signal schema for raw webhooks — additionalProperties: true or you lose the body

The signal's JSON Schema is enforced by the runtime through Zod, which STRIPS any fields not declared in properties. If you declare nested objects without additionalProperties: true, every nested field arrives as an empty {} and the agent sees nothing useful.

Wrong (what looks documentative but silently destroys the payload):

yamlCopy code
signals:
  bb-pr-comment:
    provider: http
    config: { path: /bb-pr-comment }
    schema:
      type: object
      properties:
        actor:        { type: object, description: "Commenter" }
        comment:      { type: object, description: "Comment object" }
        pullrequest:  { type: object, description: "PR object" }
        repository:   { type: object, description: "Repo object" }

The agent's inputs.actor, inputs.comment, etc. all become {} — LLM templates render as empty, Python agents see empty dicts.

Right — let the body through:

yamlCopy code
signals:
  bb-pr-comment:
    provider: http
    config: { path: /bb-pr-comment }
    schema:
      type: object
      additionalProperties: true

Or, if you want to document the expected shape without stripping:

yamlCopy code
schema:
  type: object
  additionalProperties: true
  properties:
    actor:        { type: object, additionalProperties: true }
    comment:      { type: object, additionalProperties: true }
    pullrequest:  { type: object, additionalProperties: true }
    repository:   { type: object, additionalProperties: true }

Rule of thumb for HTTP webhook signals: every type: object you write must be paired with additionalProperties: true, or it strips silently. The validator does not warn — the agent just sees {}.

Where the payload lands inside the workspace

Once the tunnel forwards the body to atlasd, the workspace's signal fires and the body is available to the triggered agent under ctx.input.config (or ctx.input.raw as a fallback for signal-direct invocations):

pythonCopy code
payload = ctx.input.config or ctx.input.raw

What the agent then does with the payload — extracting fields, branching on event family, posting something back to the upstream — is agent-implementation territory and out of scope for this skill.

Bitbucket Cloud — UI steps

1. Repo settings → Webhooks → Add webhook
2. Title: anything (e.g. Friday)
3. URL: paste https://<tunnel-url>/hook/raw/<workspaceId>/<signalId>
4. Secret: leave blank — the tunnel does no verification.
5. Status: Active
6. Triggers: pick the events you want.

GitHub — UI steps

1. Repo settings → Webhooks → Add webhook
2. Payload URL: https://<tunnel-url>/hook/raw/<workspaceId>/<signalId>
3. Content type: application/json (not the form-encoded default).
4. Secret: leave blank — the tunnel does no verification.
5. Which events: pick the events you want.

Tunnel-level errors