Using itWebhooks
Webhooks
A webhook runs one of your schedules when a service calls its URL: a deploy that finished, a pull request, a form. The schedule holds the job (its prompt, project, provider, and whether each run gets a new agent or the same one), so its runs, receipts, and failures show wherever schedules do.
The webhooks plugin serves the hooks over HTTP on a loopback address. Nothing outside
this machine reaches it until you expose it yourself, as with
Tailscale.
Set one up
Section titled “Set one up”-
Make the job a schedule that runs on demand, with no time of its own:
vendetta schedule add --id deploy-review --on-demand --reuse --provider claude \ --cwd /abs/project --tmux-session project \ --prompt 'A deploy just finished. Check that the site works and tell me.'--reusesends every run to the same agent;--newstarts one each time. A hook can run a cron schedule too, as Run now does. -
Give it a hook in
~/.config/vendetta/config.toml:[plugins.webhooks] listen = "127.0.0.1:8787" # the default; it must be a loopback address [plugins.webhooks.hooks.deploy] # served at /hooks/deploy schedule = "deploy-review" secret = { env = "DEPLOY_HOOK_SECRET" } # or { command = ["pass", "show", "deploy-hook"] } auth = "github" # "bearer" (the default), "github", or "hmac" body = true # pass the request body on to the agent per_minute = 6 # runs it accepts a minute, 1 to 60A hook’s name is 1 to 64 lowercase letters, digits,
-, or_. The secret comes from a command’s output or an environment variable of the worker, never from the file itself, and is at least 16 bytes. It is read when the plugin starts and again, at most once a minute, while it cannot be read or a request does not match it, so a rotated secret works without a restart. -
Save the config, and check that the plugin runs:
vendetta notify status # plugins: webhooks=running -
Call it:
curl -X POST http://127.0.0.1:8787/hooks/deploy \ -H "Authorization: Bearer $DEPLOY_HOOK_SECRET" -d '{"ref": "main"}' # {"run":"3f0c…","hook":"deploy"}
Proving a request
Section titled “Proving a request”auth |
The request carries |
|---|---|
bearer |
Authorization: Bearer SECRET |
github |
GitHub’s X-Hub-Signature-256: sha256=HEX, the HMAC-SHA256 of the exact body with the secret |
hmac |
The same signature, as sha256=HEX or bare HEX, in X-Vendetta-Signature-256, or the header signature_header names |
Forgejo and Gitea sign in a header of their own: use auth = "hmac" with
signature_header = "X-Forgejo-Signature" (or X-Gitea-Signature). To sign by hand:
body='{"ref": "main"}'
signature=$(printf %s "$body" | openssl dgst -sha256 -hmac "$DEPLOY_HOOK_SECRET" -hex | sed 's/^.* //')
curl -X POST http://127.0.0.1:8787/hooks/deploy \
-H "X-Vendetta-Signature-256: sha256=$signature" --data-binary "$body"What happens
Section titled “What happens”- The plugin answers
202with the run’s ID as soon as the run is queued, and never waits for the agent. The run goes through the scheduler as Run now does, and its history entry’s occurrence iswebhook:HOOK:RUN:vendetta schedule history --id deploy-reviewshows how it went, and the worker’s log says it in a line. - Pausing the schedule pauses its hooks: their runs end as
disabled. A failed or uncertain run stops the schedule until you check it, as any schedule’s does, and the hook’s later runs wait for that too. Nothing is ever retried. - With
body = truethe agent gets the schedule’s prompt, then the request body, marked as untrusted data in a fence the body cannot close. Control characters become�. The prompt and body together are at most 64 KiB; a longer body is cut, and the prompt says so. The body is kept nowhere: not in the schedule, its history, or the log.
| Answer | Why |
|---|---|
202 |
Queued; {"run", "hook"} |
400 |
Malformed, or sent too slowly (10 seconds) |
401 |
The secret or signature does not match |
404 |
No such hook; hooks are only at /hooks/NAME |
405 |
Not a POST |
411 |
No Content-Length, or a chunked body |
413 |
The body is over 64 KiB |
429 |
Over the hook’s per_minute, over 60 failed proofs a minute, or 16 runs already waiting; Retry-After says when |
503 |
The hook’s secret cannot be read (tried again at most once a minute), or 16 requests are already open |
Reaching it from outside
Section titled “Reaching it from outside”Expose the port with Tailscale Serve, for your own devices, or Funnel, for services on the internet:
tailscale serve --bg 8787 # https://MACHINE.TAILNET.ts.net/hooks/NAME, in your tailnet
tailscale funnel --bg 8787 # the same URL, from anywhere
tailscale serve status # what is exposed; `tailscale serve reset` removes itOnly /hooks/NAME answers, and only to a request with the hook’s secret. Use a signature
(github or hmac) when the sender supports one: a signature proves the body too, and
the secret never travels.