Skip to main content

API & webhooks

OtoDock speaks HTTP, and the reason to reach for it is webhooks — letting an outside system kick off your agents when something happens. This page covers how to authenticate and how to wire incoming events to your agents.

Authentication with API keys​

External requests authenticate with an API key. Any user creates one under User Settings → API Keys; it fires that user's own triggers, and it's shown only once — copy it when you create it. Keys are scoped to firing triggers — they're the credential for your webhooks, not a general key to the dashboard. Send it as a bearer token:

Authorization: Bearer <your-api-key>

Revoke a key any time from the same page. For a shared agent's triggers, use a key scoped to that agent instead — an agent manager creates those on the same page.

Webhook endpoints live under /v1 at your install's address (for example https://otodock.example.com/v1/...), and responses are JSON.

Incoming webhooks​

The headline capability: give an external system a URL, and when it sends an event, your agent acts on it. Every trigger you create has its own webhook URL.

Your own webhooks​

Wire up any system — an automation tool, a script, a device — to POST to a trigger's URL:

POST /v1/webhooks/user/{username}/{trigger}      # a personal trigger
POST /v1/webhooks/agent/{agent}/{trigger}        # a shared agent trigger

Send your event as a JSON body and include your API key. The data you send is handed to the agent — your task's instructions can reference the incoming fields, so the agent responds to the specifics of each event.

curl -X POST https://otodock.example.com/v1/webhooks/agent/support-bot/new-ticket \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"customer": "Acme", "priority": "high", "summary": "Login is down"}'

Connected-service webhooks​

Events from an integration like GitHub arrive under the same /v1/webhooks/ path and are verified automatically using the provider's signed-request mechanism — no API key needed. You set these up by connecting the service and subscribing to its events; see Integrations and Triggers.

Behind a login gateway​

If you run OtoDock behind a reverse proxy that forces a login on every request (Authentik, Authelia, oauth2-proxy, Cloudflare Access), a few paths must skip that login so the clients that authenticate themselves can still connect:

^/v1/webhooks/      # incoming webhooks — OtoDock authenticates these itself (Bearer key / signed request)
^/v1/images/temp/   # only if an MCP mints short-lived public image URLs (e.g. reverse-image search) — the random URL token is the auth

Everything else — the dashboard and all management endpoints — stays behind your gateway and works normally for a logged-in user. The endpoints that create triggers, keys, and subscriptions are not bypassed; they use your normal session.

Two practical notes for the live dashboard behind such a gateway:

  • Make sure your reverse proxy forwards WebSocket upgrades for /ws/. With strict forced-login gateways it's simplest to also exempt /ws/ from the login redirect — a WebSocket handshake can't follow one. That's not an exposure: OtoDock authenticates the socket itself with your logged-in session.
  • Exempting /favicon.png is a cosmetic nicety — browsers fetch it before the login redirect completes, so behind a gateway the tab icon otherwise stays blank.

Good to know​

  • Requests are JSON, and errors come back with a clear status and message.
  • Large requests are capped and abusive rates are limited (you'll get a 429 with a Retry-After if you go too fast).
  • Webhooks aren't deduplicated — sending the same event twice fires the trigger twice, so handle retries on your side if your source might resend.

Next steps​