AgentVera webhooks guide

What a webhook does

Each webhook gets a secret URL. For a request to that URL, AgentVera can:

• Open a kanban card on the board and column you choose, with labels if you like.
• Create an agent task: Claude or Codex, running either on your Runner or on the desktop app that has the card’s project open.

When the agent finishes its turn, a summary of the result is written to the card as an internal comment by “AgentVera”. Follow tasks live at app.agentvera.dev/tasks.

Creating a webhook

Organization owners and admins create webhooks. On app.agentvera.dev/webhooks, click “Yeni webhook” (new webhook) and follow these steps:

1. Give the webhook a name.
2. Card action: pick the board and column where the card opens.
3. Task action: pick the agent kind (Claude or Codex) and the target. The target is a specific Runner (optionally with a working folder) or “Proje” (project), meaning the desktop app that has the card’s project open. Project tasks are always tied to a card.
4. Template: write the card title, description and agent prompt with {{…}} placeholders.
5. Filter (optional): only process certain requests.
6. Signature (recommended): choose GitHub or generic HMAC-SHA256 verification.
7. Save. The webhook URL and signing secret are shown only once; copy both.

You can rotate the URL or secret later; the old URL stops working immediately.

Templates and placeholders

Placeholders read values from the incoming request:

• {{body.issue.title}}: fields of the JSON body, as a dot path. Use numbers for array items: {{body.commits.0.id}}.
• {{headers.x-github-event}}: request headers, lowercased.
• {{query.foo}}: query parameters in the URL.

A missing value becomes empty; objects are inserted as JSON. Whitespace in the card title collapses to single spaces and the title is capped at 300 characters. The card description is sanitized; the prompt goes to the agent exactly as written.

Filter

A filter requires a value in the request (path) to equal a given value or be one of the values you allow. For example, for newly opened GitHub issues only, set path to body.action and the value to opened. Requests that don’t match are logged as “ignored” and open no card or task.

Signature verification

• GitHub: the X-Hub-Signature-256 header is verified with the signing secret.
• Generic HMAC-SHA256: the hex signature of the body is expected in a header you name; a sha256= prefix is accepted too.

Always use signing when the source supports it. For sources that can’t sign, security rests on the secret URL; rotate it if it leaks.

Example: tasks from GitHub issues

1. In the GitHub repository, go to Settings → Webhooks → Add webhook.
2. Enter the AgentVera webhook URL as the Payload URL, application/json as the Content type and the signing secret as the Secret.
3. Choose the “Issues” event and save.

The template in AgentVera:

Title:       {{body.issue.title}}
Description: {{body.issue.body}}
Filter:      body.action = opened
Prompt:
GitHub issue #{{body.issue.number}}: {{body.issue.title}}

{{body.issue.body}}

Investigate this bug, fix it and run the tests.

Sentry and other JSON sources

Point any service at the webhook URL. If the source can sign, use generic HMAC-SHA256; if not, rely on the secret URL. Map the fields the source sends into the template with placeholders. To try it from your own system:

curl -X POST "https://app.agentvera.dev/hooks/<id>/<secret>" \
  -H "content-type: application/json" \
  -d '{"title": "Checkout page returns 500", "detail": "..."}'

Requests, responses and limits

• POST only; the body is JSON or form-encoded, up to 1 MB.
• 60 requests a minute per webhook, 600 a minute per IP.
• 202: accepted (requests ignored by the filter also get 202).
• 401: invalid signature.
• 403: the organization’s plan doesn’t include webhooks.
• 404: wrong URL, disabled webhook or suspended organization (all get the same response).
• 413: body too large. 429: rate limited.

Deliveries and tasks

• Every request is logged under the webhook’s deliveries with a status: ok, ignored, rejected or failed, plus whether a card or task was created.
• The request content (body, headers and query; Authorization, cookie and signature headers excluded) is kept for 7 days and can be replayed with the current template during that time, which helps after you fix a template. After that the content is deleted and the summary stays.
• app.agentvera.dev/tasks shows tasks live: queued, claimed, running, done or failed. Admins can cancel tasks.
• If the Runner is offline, the task waits in the queue and is sent when the runner connects. A task that makes no progress for 30 minutes goes back to the queue once; the second time it’s marked failed.

Security

Webhook content goes into the agent’s prompt as it is. Anyone who can write an issue in a repository could try to instruct the agent.

• Connect only sources and repositories you trust.
• Use filters to narrow which requests are processed.
• On Runner, use roots to limit the folders agents can reach.
• Always use signing when the source supports it; the URL is a secret, rotate it if it leaks.
• Request content is never written to logs; the secret part of the URL is redacted in logs.