Skip to main content

Webhook triggers

A trigger is a secret URL on this machine. Each event that an outside service sends to it either sends a message to one existing conversation or starts a new conversation in a project. Events reach the machine directly through Tailscale Funnel, so overdeck.ai never sees them and you need no overdeck.ai account.
Added in v0.73.0. Manage triggers with pan triggers or Settings → Anywhere → Triggers.

What a trigger does

Every trigger has one target:
  • Conversation target. Each event is sent as one message to an existing conversation, the same way the composer sends one. The conversation must still be open; an ended or archived conversation answers 410.
  • Project target. Each event starts one new conversation in a registered project. The conversation’s first message is your prompt template followed by the event. A project target needs a prompt template. With pan triggers add you can also set the model, harness and effort for the conversations it starts; unset values follow the normal defaults.
A trigger delivers every event type it receives, including GitHub’s ping event. It has no repository or event-type filter, because the URL is the authorization and GitHub and Stripe already let you choose which events to send. A trigger can only send a message or start a conversation. It never answers a question, picks a menu option or approves a permission (see Limits and refusals).

Create a trigger

From the terminal:
--conversation takes a conversation name or its numeric id; the trigger stores the name. A trigger name is 1 to 64 characters: letters, digits, spaces, ., _ and -. See pan triggers for every flag. From the dashboard: open Settings → Anywhere, then Add trigger in the Triggers panel. Either way you get the trigger’s URL once:
The last path segment is the URL secret. Overdeck keeps only its SHA-256 hash, so it cannot show the URL again. If you lose it, remove the trigger and add a new one. When a trusted address on a .ts.net host is saved (Settings → Anywhere), Overdeck fills in the real host; otherwise it prints the <machine>.<tailnet> placeholder for you to replace. pan triggers add also prints a local test URL, http://127.0.0.1:<dashboard port>/hooks/…, which works on this machine without Funnel:

Signing secrets

A trigger’s verification kind is none, github or stripe. With github or stripe, the dashboard checks the event’s signature over the exact request bytes before it does anything else with the body. A trigger with github or stripe and no signing secret refuses every event with 503. GitHub. When you create a github trigger without --signing-secret, Overdeck generates a secret and shows it once with the URL. In the repository’s Settings → Webhooks → Add webhook form, paste the URL into Payload URL and the secret into Secret. Either content type works. GitHub signs each event with X-Hub-Signature-256. Stripe. Stripe makes the secret, so create the trigger first, create the endpoint in Stripe with the trigger’s URL, then copy the endpoint’s whsec_… secret into the trigger. pan triggers add for a stripe trigger with no secret prints a set-secret reminder line:
set-secret reads the secret from one line of standard input (or pass --secret). In the dashboard, click Set signing secret on the trigger’s row in Settings → Anywhere → Triggers. Stripe signs each event with Stripe-Signature. Overdeck accepts any matching v1 signature, so a rolled secret keeps working during Stripe’s overlap window, and it refuses an event whose timestamp is more than 300 seconds before or after this machine’s clock. No route or command shows a signing secret after you set it. To change one, set it again.

Publish with Tailscale Funnel

Tailscale Funnel publishes one local address on the public internet through Tailscale’s relays. Overdeck publishes the /hooks path on port 8443. If you turn on Public MCP (see Public MCP for hosted bots), it adds /mcp, /.well-known and /oauth on the same port. Prerequisites:
  1. Tailscale is installed on this machine and signed in to your tailnet.
  2. HTTPS certificates are on for the tailnet (admin console → DNS → HTTPS Certificates).
  3. The tailnet policy gives this machine the funnel node attribute.
  4. Your user may run Tailscale serve commands. Run this once:
Turn Funnel on for the trigger route (replace 3011 if your dashboard API port is different; pan triggers add and the Settings panel print the command with your port):
Turn it off:
The target URL repeats /hooks because Funnel strips the mount path before it proxies the request. Port 8443 keeps Funnel off port 443, where Tailscale Serve may publish your dashboard to the tailnet; Funnel is allowed per host and port, so funneling 443 would also publish that dashboard. The public URL form is:
Overdeck does not run the tailscale command itself.

What the agent sees

The event never reaches the agent as raw text. Overdeck wraps it in a fixed envelope:
  • The message always starts with fixed text, so a body that starts with /handoff or any other command never runs as one.
  • The nonce is random for each event, so the body cannot fake the end marker.
  • source is github or stripe only when that signature was verified, else unsigned.
  • Control characters in the body (carriage returns, Ctrl-C, escape sequences) become �.
  • At most 44 KiB of the body is included. A longer body is cut, marked truncated=yes, and ends with [truncated: <n> more bytes not shown]. The cap keeps the whole message under the 50,000-character limit that every conversation message has. The signature is still checked over the full body, up to 1 MiB.

Limits and refusals

  • Rate limits. A project trigger handles at most 6 events per rolling hour and a conversation trigger at most 60. Every event that passes the signature and CPU checks counts, including one then refused because the conversation waits for an answer or is gone. The count lives in the dashboard’s memory and resets when the dashboard restarts.
  • Pending input. While the target conversation has an open question, plan approval, permission prompt or menu, the trigger answers 503 instead of sending, so an event can never answer it.
  • CPU pressure. While the host’s CPU is saturated, every trigger answers 503.
  • Nothing is queued on the Funnel URL. A refused event is not stored. GitHub does not retry failed deliveries (use Redeliver in the webhook’s Recent Deliveries); Stripe retries non-2xx deliveries for up to three days. To keep events that arrive while this machine is off, give the trigger a directory inbox.
  • “Started” means the conversation was created and its launch requested; the agent becoming ready is not part of the HTTP answer.

Security

  • The URL is a bearer secret. Anyone who has it can send events. Treat it like a password, and remove the trigger if it leaks.
  • Funnel requests reach only POST /hooks/*, plus the Public MCP paths while Public MCP is on. Tailscale marks every funneled request with the Tailscale-Funnel-Request header and removes any copy a client sends. The dashboard answers such a request with 404 on every other method and path (even with a credential), never treats it as a local caller, refuses it a dashboard session, and refuses its WebSocket upgrades.
  • overdeck.ai never sees Funnel events. They travel from the sender through Tailscale’s relays to this machine.
  • Unknown URLs cost nothing. The dashboard checks the trigger id and URL secret before it reads any of the body, and it stops reading a body as soon as it passes 1 MiB, even when the sender gives no Content-Length.
  • Logs name the trigger id and the outcome only, never the body or a secret.
  • The trigger store is ~/.overdeck/triggers.json, mode 0600. It holds the URL secret’s hash and the signing secrets in plain text, because the machine must compute the HMAC.

Hold events with the directory inbox

A trigger can also have an overdeck.ai directory inbox: a second URL, https://connect.overdeck.ai/h/<id>, that accepts events while this machine is offline and delivers them when it comes back. It needs a signed-in machine (pan account login) on the Anywhere plan; the free account does not include it.
  • Create one with pan triggers add <name> … --inbox, or tick Hold events while this machine is offline (overdeck.ai inbox, Anywhere plan) in Settings → Anywhere → Add trigger. The checkbox appears only while this machine is signed in, the directory is online and the account’s plan includes the inbox. The inbox URL is printed or shown once, in place of the Funnel URL. Paste it into the sender’s webhook settings. The trigger’s Funnel URL also works, but neither the dashboard nor pan triggers add prints it when you add an inbox; pan triggers add … --inbox --json includes it as hookPath and url.
  • Size. The inbox takes events of at most 256 KiB and answers 413 for anything larger (the Funnel URL takes up to 1 MiB).
  • Hold time. Each event waits up to 24 hours. An event that is still undelivered after 24 hours is deleted.
  • Order. When this machine comes back online, it receives every held event at once and runs them one at a time, oldest first, through the same checks as a Funnel event: signature, rate limit, CPU hold and pending input. A busy answer (503, 429) is retried after the Retry-After time, at least a minute later; a final answer (delivered, 401, 404, 410, 413) removes it.
  • Stripe timestamps. A Stripe signature must be within 300 s of when the inbox received the event, not of when this machine processes it, so a held Stripe event still verifies.
  • The inbox answers at once with 202 { "queued": true }; it never waits for this machine. A full inbox (200 events in this inbox, or 64 MiB for the account) answers 429 with Retry-After: 3600. More than 120 events a minute to one inbox answer 429 with Retry-After: 60. When the account’s plan no longer includes the inbox, it answers 403.
  • Removing the trigger in Settings → Anywhere → Triggers deletes its inbox and every event it holds. pan triggers remove deletes only the trigger: its inbox keeps accepting events, and this machine discards them because no trigger owns them. Remove inbox triggers from the dashboard.

What the inbox can see

overdeck.ai sees each event once, in memory, while it accepts it: the body and the Content-Type, User-Agent, X-GitHub-Event, X-GitHub-Delivery, X-Hub-Signature-256 and Stripe-Signature headers. It seals that copy at once to this machine’s public key (crypto_box_seal) and stores only the sealed copy, which only this machine can open. It never holds the trigger’s signing secret, so it cannot forge an event that passes the signature check. Its logs name the message type, the machine and the outcome, never the body or the inbox URL.

Get help

Still stuck? Ask on the Overdeck Discord or file a GitHub Issue.