Letta Forgejo Webhook

A compatibility layer that receives Forgejo webhook events and forwards them as formatted messages to lettabot's chat API.

How It Works

Forgejo sends webhook payloads using the Gitea webhook format. This app listens for those payloads on a /webhook endpoint, converts them into human-readable messages, and forwards them to lettabot's /api/v1/chat endpoint.

Setup

1. Run the Webhook Server

Set the required environment variables and start the server:

Variable	Required	Default	Description
LETTABOT_URL	Yes	http://localhost:8080	Base URL of your lettabot instance
LETTABOT_API_KEY	Yes	(empty)	API key for authenticating with lettabot
LETTABOT_AGENT	No	(none)	Target a specific lettabot agent by name
LETTABOT_AGENT_ID	No	(none)	Target a specific lettabot agent by ID
WEBHOOK_SECRET	No	(none)	HMAC-SHA256 secret to verify webhook signatures
PORT	No	8080	Port the webhook server listens on
HOST	No	0.0.0.0	Host/interface to bind to

export LETTABOT_URL="https://your-lettabot-instance.example.com"
export LETTABOT_API_KEY="your-api-key"
export WEBHOOK_SECRET="your-shared-secret"  # optional but recommended
export PORT=9000

./gradlew run

The server exposes:

• POST /webhook — receives Forgejo/Gitea webhook payloads
• GET /health — health check endpoint

2. Configure Forgejo to Send Webhooks

Forgejo uses the Gitea webhook type — there is no need for a "custom" webhook template.

Steps:

1. Go to your Forgejo repository (or organization) → Settings → Webhooks

2. Click "Add Webhook"

3. Select "Gitea" from the dropdown (this is the correct type for Forgejo)

   Note: Even though you're using Forgejo, select "Gitea" — Forgejo uses the same webhook payload format as Gitea. The X-Gitea-Event header it sends is fully supported by this app.

4. Fill in the webhook settings:

   Field	Value
   Target URL	http://your-server:9000/webhook
   HTTP Method	POST
   Content Type	application/json
   Secret	Same value as your WEBHOOK_SECRET env variable (leave blank if not using signature verification)

5. Under "Trigger On", choose which events to send:

   • Push Events — code pushes
   • Issue Events — issue created/closed/reopened/edited
   • Issue Comment — comments on issues
   • Pull Request Events — PRs opened/closed/merged
   • Pull Request Comment — comments on pull requests
   • Create — branch/tag creation
   • Delete — branch/tag deletion
   • Release — release published/edited
   • Fork — repository forked

   Or simply select "All Events" to forward everything.

6. Make sure "Active" is checked

7. Click "Add Webhook"

Testing the Webhook

After adding the webhook, Forgejo shows a "Test Delivery" button. Click it to send a test ping event and verify the connection works. You should see a 200 OK response.

You can also check the "Recent Deliveries" section on the webhook settings page to see the request/response details for each delivery.

Supported Events

Forgejo Event	Example Message
push	[Push] user pushed 3 commit(s) to main in org/repo
issues	[Issue opened] user opened issue #42 in org/repo
issue_comment	[Comment created] user created a comment on issue #42 in org/repo
pull_request	[PR opened] user opened pull request #10 in org/repo
pull_request_comment	[PR Comment created] user created a comment on PR #10 in org/repo
create	[Create] user created branch 'feature-x' in org/repo
delete	[Delete] user deleted 'old-branch' in org/repo
release	[Release published] user published release 'v1.0' (v1.0) in org/repo
fork	[Fork] user forked org/repo
Other events	[Forgejo: event_name] Event 'action' triggered by user in org/repo

Building

./gradlew build

Fat JAR (Shadow)

Build a single executable JAR with all dependencies included:

./gradlew shadowJar

The fat JAR will be at build/libs/letta-forgejo-webhook-1.0-SNAPSHOT-all.jar. Run it with:

java -jar build/libs/letta-forgejo-webhook-1.0-SNAPSHOT-all.jar

Deployment (Systemd)

To run the application as a service on Linux, you can use a systemd unit file. An example is provided in letta-forgejo-webhook.service.

1. Copy the JAR to your target location:

   cp build/libs/letta-forgejo-webhook-1.0-SNAPSHOT-all.jar /home/lettabot/letta-forgejo-webhook.jar
   

2. Edit the environment variables in letta-forgejo-webhook.service as needed.

3. Install the service:

   sudo cp letta-forgejo-webhook.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable letta-forgejo-webhook
   sudo systemctl start letta-forgejo-webhook
   

4. Check the status:

   sudo systemctl status letta-forgejo-webhook
   

Running Tests

./gradlew test