Webhook Setup

AgenticKode can automatically create task runs when issues are created or updated in your issue tracker. Configure inbound webhooks to connect your repositories and project management tools.

How It Works

1. An issue is created or labeled in your issue tracker
2. The tracker sends a webhook event to AgenticKode
3. AgenticKode matches the event to a project and dispatches a flow prompt
4. A new task run is created and queued for the worker

The task description is extracted from the issue title and body. Issue labels can route the run to a specific flow prompt (e.g. implement); otherwise the default implement flow runs.

Webhook URL

Your AgenticKode instance exposes webhook endpoints at:

https://your-agentickode-host/api/webhooks/{provider}

Where {provider} is one of: github, gitlab, gitea, plane.

GitHub

Create the Webhook

1. Go to your repository on GitHub
2. Navigate to Settings > Webhooks > Add webhook
3. Configure:
   • Payload URL: https://your-host/api/webhooks/github
   • Content type: application/json
   • Secret: (optional) shared secret for signature verification
   • Events: Select Issues (or choose individual events)
4. Click Add webhook

Supported Events

Token Requirements

The GITHUB_TOKEN needs repo scope to create branches and pull requests in response to webhook-triggered runs.

GitLab

Create the Webhook

1. Go to your project on GitLab
2. Navigate to Settings > Webhooks
3. Configure:
   • URL: https://your-host/api/webhooks/gitlab
   • Secret token: (optional) for verification
   • Trigger: Check Issues events
4. Click Add webhook

Supported Events

Token Requirements

The GITLAB_TOKEN needs api scope for full repository access.

Gitea

Create the Webhook

1. Go to your repository on Gitea
2. Navigate to Settings > Webhooks > Add Webhook > Gitea
3. Configure:
   • Target URL: https://your-host/api/webhooks/gitea
   • HTTP Method: POST
   • Content Type: application/json
   • Secret: (optional) shared secret
   • Trigger On: Select Custom Events > Issues
4. Click Add Webhook

Supported Events

Token Requirements

The GITEA_TOKEN needs repository read/write access.

Plane

Create the Webhook

1. Go to your Plane workspace
2. Navigate to Settings > Webhooks
3. Configure:
   • URL: https://your-host/api/webhooks/plane
   • Secret key: (optional) for verification
   • Events: Enable Issue events
4. Save the webhook

Supported Events

Flow-Prompt Matching

When a webhook event arrives, AgenticKode:

1. Identifies the project by matching the repository URL from the event payload
2. Extracts labels from the issue
3. Matches labels to a flow prompt via its triggers (e.g. implement, pr_review)
4. Dispatches the run — selecting the agent and trigger mode

If no flow prompt matches, the default implement flow prompt runs.

Example Flow-Prompt Routing

A flow prompt's triggers decide which events route to it. For example, an implement flow prompt that runs Claude when an issue is labelled bug:

• Trigger: issue_event, action labeled, label filter bug
• Agent: Claude CLI

PR-review is wired separately — opening or labelling a PR with ai-review dispatches the pr_review flow prompt.

Issue Tracker Updates

After a run completes, AgenticKode updates the source issue:

• Posts a comment with the run result and PR link
• Updates issue status if configured
• Includes cost summary and phase timings

This is handled by the task_source_updater service during the finalization phase.

Troubleshooting

Webhook Not Triggering

• Verify the webhook URL is reachable from the internet (or your network)
• Check the webhook delivery log in your git provider for HTTP response codes
• Ensure the project's git URL in AgenticKode matches the repository sending the webhook

Project Not Found

• The repository URL in the webhook payload must match a configured project
• Check that the git URL format matches (HTTPS vs SSH)

Wrong Template Applied

• Verify issue labels match the flow prompt's trigger configuration
• Check flow-prompt priority if multiple flow prompts match

Next Steps

• Worker Pipeline — Understand what happens after a run is triggered
• Configuration — Workflow template and notification setup