BetaHub Webhooks Documentation

Overview

Webhooks in BetaHub allow you to receive real-time HTTP notifications when important events occur in your projects. Instead of constantly checking for updates, webhooks push information directly to your external systems, enabling seamless integration with tools like Slack, Discord, custom dashboards, or any service that can receive HTTP requests.

What are Webhooks?

Webhooks are HTTP callbacks that BetaHub sends to your specified URL whenever a trigger event occurs. Think of them as “reverse API calls” - instead of your system asking BetaHub for updates, BetaHub proactively sends updates to your system.

Benefits

• Real-time notifications: Get instant updates when issues, feature requests, or tickets are created
• Automated workflows: Trigger actions in external systems without manual intervention
• Custom integrations: Connect BetaHub to any system that can receive HTTP requests
• Flexible payload formats: Customize the data format to match your receiving system’s requirements

How It Works

1. Event occurs: A user reports a bug, submits a feature request, or creates a support ticket
2. Webhook triggers: BetaHub identifies active webhooks configured for that event type
3. HTTP request sent: BetaHub sends a customized HTTP request to your specified URL
4. Your system responds: Your endpoint receives and processes the webhook data
5. Retry if needed: Failed deliveries are automatically retried up to 3 times

Getting Started

Accessing Webhooks

1. Navigate to your project
2. Go to Integrations from the project menu
3. Click the Webhooks tab
4. Click “New Webhook” to create your first webhook

Creating Your First Webhook

Follow these steps to set up a basic webhook:

1. Description: Enter a meaningful name (e.g., “Slack Notifications”, “Issue Tracker Sync”)
2. Event Type: Choose which event should trigger this webhook
3. URL: Enter the endpoint URL where BetaHub should send notifications
4. HTTP Method: Select POST (most common), PUT, or PATCH
5. Payload: Define the JSON structure and content to send
6. Headers (Optional): Add authentication tokens or content-type specifications
7. Test: Use the built-in test feature to verify your configuration
8. Save: Activate your webhook

Event Types

BetaHub supports three webhook event types, each triggered by different user actions:

Issue Created

Triggered when: A user reports a new bug or issue in your project

Common use cases:

• Notify development team in Slack
• Create tickets in external bug tracking systems
• Update project dashboards
• Log issues in monitoring systems

Available data: Complete issue details including title, description, reproduction steps, priority, and reporter information.

Feature Request Created

Triggered when: A user submits a new feature suggestion or enhancement request

Common use cases:

• Notify product team of new suggestions
• Add requests to product roadmap tools
• Track feature demand in analytics systems
• Send acknowledgment emails to requesters

Available data: Feature request details including title, description, status, and submitter information.

Ticket Created

Triggered when: A user creates a new support ticket

Common use cases:

• Alert support team immediately
• Create tickets in help desk systems
• Track support volume metrics
• Route tickets based on priority or type

Available data: Support ticket details including title, description, priority, status, and reporter information.

Payload Templates & Variables

Variable Syntax

Use double curly braces to insert dynamic values: ``

Available Variables

Issue Created Event

{
  "id": "",
  "title": "",
  "description": "",
  "steps_to_reproduce": "",
  "status": "",
  "priority": "",
  "url": "",
  "project_name": "",
  "reported_by": "",
  "reported_by_url": ""
}

Feature Request Created Event

{
  "id": "",
  "title": "",
  "description": "",
  "status": "",
  "url": "",
  "project_name": "",
  "reported_by": "",
  "reported_by_url": ""
}

Ticket Created Event

{
  "id": "",
  "title": "",
  "description": "",
  "status": "",
  "priority": "",
  "url": "",
  "project_name": "",
  "reported_by": "",
  "reported_by_url": ""
}

Payload Examples

Slack Integration

{
  "text": "New  issue in ",
  "attachments": [
    {
      "color": "danger",
      "title": "",
      "title_link": "",
      "text": "",
      "fields": [
        {
          "title": "Priority",
          "value": "",
          "short": true
        },
        {
          "title": "Reported by",
          "value": "",
          "short": true
        }
      ]
    }
  ]
}

Discord Integration

{
  "embeds": [
    {
      "title": "",
      "description": "",
      "url": "",
      "color": 15158332,
      "fields": [
        {
          "name": "Project",
          "value": "",
          "inline": true
        },
        {
          "name": "Priority",
          "value": "",
          "inline": true
        },
        {
          "name": "Reported by",
          "value": "",
          "inline": true
        }
      ]
    }
  ]
}

Generic REST API

{
  "event_type": "issue_created",
  "issue": {
    "id": "",
    "title": "",
    "description": "",
    "priority": "",
    "status": "",
    "project": "",
    "reporter": {
      "name": "",
      "profile_url": ""
    },
    "betahub_url": ""
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Configuration Options

HTTP Methods

• POST: Most commonly used, creates new resources
• PUT: Updates entire resources, idempotent
• PATCH: Partially updates resources

Custom Headers

Add headers for authentication or content specification:

Common examples:

Content-Type: application/json
Authorization: Bearer your-token-here
X-API-Key: your-api-key
User-Agent: BetaHub-Webhook/1.0

Active/Inactive Status

• Active: Webhook will fire when events occur
• Inactive: Webhook is disabled but configuration is preserved

URL Requirements

• Must be a valid HTTP or HTTPS URL
• HTTPS is strongly recommended for security
• Must be publicly accessible (BetaHub needs to reach it)
• Should respond with 2xx status codes for successful delivery

Testing & Debugging

Built-in Test Feature

BetaHub provides a comprehensive testing system:

1. Configure webhook: Set up URL, payload, and headers
2. Click “Test”: Sends a request using mock data
3. Review results: See request payload, response code, and response body
4. Iterate: Modify configuration and test again

Mock Data

Test requests use realistic but fake data:

• Issue ID: 999999
• Title: “Test Issue”
• Description: “This is a test issue for webhook testing”
• Reporter: Current user
• All other fields populated with appropriate test values

Interpreting Test Results

Successful Test (2xx Response)

Response Code: 200
Response Message: OK
Response Body: {"status": "received", "message": "Webhook processed successfully"}

Failed Test (4xx/5xx Response)

Response Code: 404
Response Message: Not Found
Response Body: {"error": "Endpoint not found"}

Testing Tips

1. Start simple: Test with a basic payload first
2. Check your endpoint: Ensure it’s running and accessible
3. Validate JSON: Use a JSON validator for complex payloads
4. Monitor logs: Check your receiving system’s logs
5. Test error scenarios: Temporarily break your endpoint to test retry behavior

Security & Best Practices

HTTPS Requirement

• Always use HTTPS URLs for production webhooks
• BetaHub verifies SSL certificates (VERIFY_PEER mode)
• Self-signed certificates will be rejected

Authentication

Since webhooks are sent over the internet, secure your endpoints:

Header-based Authentication

Authorization: Bearer your-secret-token
X-Webhook-Secret: your-shared-secret

Signature Verification

While BetaHub doesn’t currently provide HMAC signatures, you can implement your own verification:

1. Include a secret token in headers
2. Verify the token in your receiving endpoint
3. Reject requests with invalid or missing tokens

Rate Limiting

• BetaHub respects reasonable rate limits
• Failed deliveries are retried with exponential backoff
• Configure your endpoint to handle bursts of activity

Error Handling

Automatic Retries: Failed webhooks are retried up to 3 times with increasing delays

Timeout Settings: Requests timeout after a reasonable period (typically 30 seconds)

Error Logging: Check BetaHub logs and your system logs for delivery issues

Best Practices

1. Idempotent endpoints: Handle duplicate deliveries gracefully
2. Quick responses: Return 2xx status codes promptly
3. Async processing: Perform heavy work after responding to the webhook
4. Monitor delivery: Track webhook success rates and response times
5. Secure secrets: Store authentication tokens securely
6. Validate payloads: Always validate incoming webhook data

Troubleshooting Guide

Common Issues

Webhook Not Triggering

• Check webhook status: Ensure webhook is marked as “Active”
• Verify event type: Confirm the webhook is configured for the correct event
• Test the trigger: Manually create the type of event that should trigger the webhook
• Check project permissions: Ensure the webhook creator has appropriate access

Connection Errors

SSL Certificate Issues:

Error: SSL certificate verification failed
Solution: Ensure your endpoint has a valid SSL certificate

DNS Resolution Failures:

Error: getaddrinfo: Name or service not known
Solution: Verify the URL is correct and the domain is publicly accessible

Connection Timeouts:

Error: Net::ReadTimeout
Solution: Ensure your endpoint responds quickly (< 30 seconds)

Payload Issues

Invalid JSON Syntax:

• Use a JSON validator to check payload format
• Ensure proper escaping of quotes and special characters
• Test with simple payload first

Variable Substitution Errors:

• Check variable names for typos
• Ensure variables are available for the selected event type
• Variables are case-sensitive

Authentication Failures

Response Code: 401 Unauthorized
Solution: Verify authentication headers and tokens

Response Code: 403 Forbidden  
Solution: Check API permissions and rate limits

Debugging Steps

1. Use the test feature: Start with BetaHub’s built-in testing
2. Check endpoint logs: Monitor your receiving system’s logs
3. Simplify the payload: Test with minimal JSON structure
4. Verify network connectivity: Ensure BetaHub can reach your endpoint
5. Test manually: Send requests to your endpoint using curl or Postman
6. Monitor webhook status: Check if webhooks become inactive due to repeated failures

Getting Help

If you continue experiencing issues:

1. Check the webhook test results for specific error messages
2. Review your endpoint’s error logs
3. Verify the payload format matches your system’s expectations
4. Contact BetaHub support with webhook configuration details and error messages

Integration Examples

Slack Workspace Notifications

Creating a Slack Webhook URL:

1. Create a Slack App
   • Visit the Slack API website
   • Click “Create New App” and choose “from scratch”
   • Give your app a name and select a workspace
   • Click “Create App”
2. Enable Incoming Webhooks
   • In your app settings, find “Incoming Webhooks” in the features section
   • Toggle the feature to “On” to activate it
   • The settings page will refresh with additional options
3. Add Webhook to Workspace
   • Scroll down and click “Add New Webhook to Workspace”
   • Select the channel where you want to receive messages
   • Click “Allow” to authorize the app
4. Get Your Webhook URL
   • You’ll be redirected back to your app settings
   • Copy the newly generated webhook URL from the “Webhook URLs for Your Workspace” section
   • The URL format: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

Testing Your Webhook:

curl -X POST -H 'Content-type: application/json' \
  --data '{"text":"Hello from BetaHub! Webhook test successful."}' \
  YOUR_WEBHOOK_URL

BetaHub Configuration:

1. In BetaHub, go to Integrations → Webhooks
2. Create a new webhook with your Slack URL
3. Use the payload template below

Learn More: Official Slack Webhooks Documentation

Payload Template:

{
  "text": "🐛 New issue reported in ",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*<|>*\n"
      }
    },
    {
      "type": "context",
      "elements": [
        {
          "type": "mrkdwn",
          "text": "Priority:  | Reporter: "
        }
      ]
    }
  ]
}

Discord Server Integration

Creating a Discord Webhook URL:

1. Prerequisites
   • Discord account with access to the target server
   • “Manage Webhooks” permission on the server (this is a powerful permission - use carefully)
2. Access Server Settings
   • Open Discord and navigate to your server
   • Click on the server name at the top-left corner
   • Select “Server Settings” from the dropdown menu
3. Navigate to Integrations
   • In the server settings menu, find “Integrations” in the left sidebar
   • Click on “Integrations” to access integration options
4. Create Webhook
   • Find the “Webhooks” section and click on it
   • Click “Create Webhook” to start configuration
   • Configure your webhook:
     • Name: Enter a name (appears as the message sender)
     • Channel: Select the target text channel
     • Avatar: Upload a custom avatar image (optional)
5. Copy Webhook URL
   • Click “Copy Webhook URL” to save the URL to your clipboard
   • The URL format: https://discord.com/api/webhooks/[webhook-id]/[webhook-token]
   • Save your configuration

Alternative Method:

• Right-click on any text channel → “Edit Channel” → “Integrations” → “Create Webhook”

Testing Your Webhook:

curl -X POST -H 'Content-Type: application/json' \
  -d '{"content": "Hello from BetaHub! Webhook test successful."}' \
  YOUR_DISCORD_WEBHOOK_URL

BetaHub Configuration:

1. In BetaHub, go to Integrations → Webhooks
2. Create a new webhook with your Discord URL
3. Set HTTP method to POST
4. Add header: Content-Type: application/json
5. Use the payload template below

Learn More: Official Discord Webhooks Documentation

Custom Dashboard Integration

Setup:

1. Create an endpoint in your application to receive webhooks
2. Process the incoming data and update your dashboard
3. Return appropriate HTTP status codes

Example Endpoint (Python/Flask):

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/betahub-webhook', methods=['POST'])
def handle_webhook():
    data = request.get_json()
    
    # Verify authentication (optional)
    auth_token = request.headers.get('Authorization')
    if not verify_token(auth_token):
        return jsonify({'error': 'Unauthorized'}), 401
    
    # Process the webhook data
    issue_id = data.get('id')
    title = data.get('title')
    priority = data.get('priority')
    
    # Update your system
    update_dashboard(issue_id, title, priority)
    
    # Return success response
    return jsonify({'status': 'received'}), 200

Monitoring and Analytics

Track webhook deliveries and system health:

{
  "event": "betahub_webhook",
  "source": "",
  "issue_id": "",
  "priority": "",
  "timestamp": "",
  "metadata": {
    "title": "",
    "reporter": "",
    "url": ""
  }
}

Conclusion

BetaHub webhooks provide a powerful way to integrate your project management workflow with external systems. By following this guide, you can set up reliable, secure webhook integrations that keep your team informed and your systems synchronized.

Remember to:

• Test thoroughly before going live
• Implement proper error handling and security
• Monitor webhook delivery success rates
• Keep payloads simple and focused on essential data

For additional support or advanced integration scenarios, consult the BetaHub support documentation or contact the support team.