Skip to content
Docs0.9GitHubInstall

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.

  1. 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.'

    --reuse sends every run to the same agent; --new starts one each time. A hook can run a cron schedule too, as Run now does.

  2. 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 60

    A 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.

  3. Save the config, and check that the plugin runs:

    vendetta notify status   # plugins: webhooks=running
  4. 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"}
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"
  • The plugin answers 202 with 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 is webhook:HOOK:RUN: vendetta schedule history --id deploy-review shows 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 = true the 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

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 it

Only /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.