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 addyou can also set the model, harness and effort for the conversations it starts; unset values follow the normal defaults.
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:
.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 isnone, 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:
- Tailscale is installed on this machine and signed in to your tailnet.
- HTTPS certificates are on for the tailnet (admin console → DNS → HTTPS Certificates).
-
The tailnet policy gives this machine the
funnelnode attribute. -
Your user may run Tailscale serve commands. Run this once:
3011 if your dashboard API port is
different; pan triggers add and the Settings panel print the command with your port):
/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:
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
/handoffor any other command never runs as one. - The nonce is random for each event, so the body cannot fake the end marker.
sourceisgithuborstripeonly when that signature was verified, elseunsigned.- 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
503instead 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 theTailscale-Funnel-Requestheader and removes any copy a client sends. The dashboard answers such a request with404on 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, mode0600. 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 norpan triggers addprints it when you add an inbox;pan triggers add … --inbox --jsonincludes it ashookPathandurl. - Size. The inbox takes events of at most 256 KiB and answers
413for 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 theRetry-Aftertime, 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) answers429withRetry-After: 3600. More than 120 events a minute to one inbox answer429withRetry-After: 60. When the account’s plan no longer includes the inbox, it answers403. - Removing the trigger in Settings → Anywhere → Triggers deletes its inbox and every
event it holds.
pan triggers removedeletes 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 theContent-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.