Webhooks

What are Webhooks?

Webhooks allow you to build integrations that respond to events in your gityar repositories. When an event occurs (like a push or issue creation), gityar sends an HTTP POST payload to a configured URL.

Creating a Webhook

Steps

1. Go to repository Settings → Webhooks
2. Click "Add Webhook"
3. Choose webhook type:
   • Gitea - For gityar/Gitea instances
   • Gogs - For Gogs instances
   • Slack - Slack notifications
   • Discord - Discord notifications
   • Dingtalk - Dingtalk notifications
   • Telegram - Telegram bot
   • Microsoft Teams - Teams notifications
   • Custom - Any HTTP endpoint
4. Configure webhook settings
5. Click "Create"

Webhook Events

Repository Events

• push - Git push to repository
• create - Branch or tag created
• delete - Branch or tag deleted
• fork - Repository forked
• release - Release published

Issue Events

• issues - Issue opened, closed, reopened
• issue_comment - Comment on issue

Pull Request Events

• pull_request - PR opened, closed, merged, synchronized

Wiki Events

• wiki - Wiki page created, edited, deleted

Webhook Configuration

Basic Settings

URL: The endpoint that will receive webhook payloads

https://your-server.com/webhook

Content Type: Format of the payload

• application/json - JSON format (recommended)
• application/x-www-form-urlencoded - Form encoded

Secret: Optional secret for payload verification

Your server should verify the X-Gitea-Signature header using HMAC-SHA256.

SSL Verification: Verify SSL certificates

• Enable for production
• Disable only for testing

HTTP Basic Auth: Add authentication

username:password

Trigger Settings

Which events?:

• Just the push event - Only trigger on pushes
• Send me everything - All events
• Let me select individual events - Choose specific events

Active: Enable or disable webhook

Testing Webhooks

Manual Test

1. Go to webhook settings
2. Click "Test Delivery" → "Push"
3. Check delivery history for results

View Delivery History

1. Open webhook details
2. See list of recent deliveries
3. Click on delivery to view:
   • Request headers
   • Request payload
   • Response headers
   • Response body
   • Response status code
   • Duration

Payload Examples

Push Event

{
  "secret": "your-secret",
  "ref": "refs/heads/main",
  "before": "6113c5d64f9c8b4e7f2e4a7b3d1c9e5f8a2b4c6d",
  "after": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "commits": [
    {
      "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
      "message": "Add new feature",
      "url": "http://localhost:3000/user/repo/commit/a1b2c3d4",
      "author": {
        "name": "John Doe",
        "email": "john@example.com"
      }
    }
  ],
  "repository": {
    "id": 1,
    "name": "my-repo",
    "full_name": "user/my-repo",
    "url": "http://localhost:3000/user/my-repo"
  },
  "pusher": {
    "name": "user",
    "email": "user@example.com"
  }
}

Webhook Security

Verify Payloads

Always verify webhook signatures:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(expected, signature)

Best Practices

• ✅ Always use HTTPS in production
• ✅ Set a strong secret
• ✅ Verify signatures
• ✅ Validate payloads
• ✅ Handle errors gracefully
• ✅ Implement retry logic
• ✅ Log webhook deliveries

Common Use Cases

CI/CD Integration

Trigger builds on push:

from flask import Flask, request
import subprocess

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    # Verify signature
    # Process payload
    
    # Trigger build
    subprocess.run(['./build.sh'])
    
    return 'OK', 200

if __name__ == '__main__':
    app.run(port=5000)

Slack Notifications

Send messages to Slack channel:

import requests

def notify_slack(message):
    url = "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
    
    payload = {
        "text": f"New push to repository: {message}"
    }
    
    requests.post(url, json=payload)

Issue Tracking

Create tickets in external systems:

def create_jira_issue(payload):
    # Extract issue information
    # Create ticket in Jira
    # Link back to gityar
    pass

Troubleshooting

Common Issues

Webhook not firing:

• Check webhook is active
• Verify event triggers
• Check URL is accessible

404 Error:

• Verify URL is correct
• Ensure endpoint exists
• Check routing

401/403 Error:

• Check authentication
• Verify credentials
• Review access controls

500 Error:

• Check server logs
• Verify payload handling
• Review error handling

Debug Tips

• Use webhook delivery history
• Test with tools like ngrok for local development
• Log all incoming webhooks
• Use webhook testing services

Next Steps

• Learn about API
• Explore Git LFS
• Read about Migration