Webhooks

A webhook gives one of your agents a URL. Anything that can send an HTTP request — Stripe, GitHub, Zapier, a form, your own backend — can hit that URL to start a run, and whatever it posts becomes context the agent reads.

Webhooks are inbound: they trigger your agents. Tulsk does not call out to your servers.

Creating a webhook

Open Chat → Schedule, expand Advanced, and add a webhook. Pick the agent it triggers, optionally pin it to a task, and give it standing instructions (“triage this alert, comment on the task if it needs a human”). Those instructions are passed to the agent on every trigger.

You can also ask in chat — “give the support agent a webhook for Stripe failures” — since webhook management is available as a chat tool.

Triggering a run

Endpoint

POST https://tulsk.io/api/hooks/{token}

Authentication

The token in the URL is the credential — it is unguessable and unique to that webhook, so no headers are required. Treat the URL as a secret; anyone holding it can start runs. Delete the webhook to revoke it.

Request

Send anything. JSON is pretty-printed for the agent; form posts and plain text pass through as-is. Bodies are read up to 64 KB, and the portion handed to the agent is capped at 6,000 characters (longer payloads are truncated with a marker).


curl -X POST https://tulsk.io/api/hooks/YOUR_TOKEN \
  -H 'content-type: application/json' \
  -d '{"event":"payment_failed","customer":"acme","amount":4900}'

Responses

Status	Meaning
`202`	Accepted — the run was queued. Body: `{ "ok": true, "accepted": true }`
`404`	Unknown token
`409`	The webhook is paused
`429`	Rate limited — 20 triggers per minute per webhook. Honour `Retry-After`

Tulsk acks in milliseconds and runs the agent afterwards, because senders like Stripe and GitHub time out in seconds and retry — waiting for the agent would double-run it. A 202 means “queued”, not “finished”.

Verification requests

Some providers probe a URL with GET before saving it. GET on a webhook URL confirms the token resolves and never triggers a run:


{ "ok": true, "name": "Stripe failures", "hint": "POST to this URL to trigger the agent" }

What the agent receives

Context

The run’s instructions are assembled from the webhook name, your standing instructions, and the event payload — so the agent knows why it woke up and what happened.

Identity

The run acts as the person who created the webhook, using their connected integrations. If that teammate disconnects an integration, runs lose those tools.

Limits

Webhook runs pass the same plan allowance and agent budget checks as any other run. If the workspace is out of allowance, the trigger is recorded but no run starts.

Results

The agent works and reports the way it always does — comments on the task, files in the workspace computer, a message in chat.

Managing webhooks over the API

Method	Endpoint	Purpose
`GET`	`/api/agents/webhooks`	List the workspace’s webhooks
`POST`	`/api/agents/webhooks`	Create one
`PATCH`	`/api/agents/webhooks/{id}`	Rename, re-point, pause, or change instructions
`DELETE`	`/api/agents/webhooks/{id}`	Delete it (revokes the URL)

These are authenticated with your Tulsk session and scoped to your workspace, unlike the trigger URL above.

Each webhook records its lastTriggeredAt and a running triggerCount, so you can tell whether a sender is actually reaching you.