Webhooks

Webhooks allow you to build custom integrations by receiving real-time HTTP notifications when events occur in BugBrain. Perfect for custom workflows, CI/CD integration, and connecting to any external system.

What are Webhooks?

Webhooks are HTTP callbacks that BugBrain sends to your specified URL when events happen. Think of them as “reverse APIs” - instead of you polling BugBrain for updates, BugBrain pushes updates to you.

How They Work

You register a webhook URL in BugBrain
You choose which events to receive
When event occurs, BugBrain sends HTTP POST to your URL
Your endpoint receives event data and processes it
Your endpoint responds with 200 OK

Use Cases

CI/CD Integration

Trigger deployments:

Test plan passes → Deploy to staging
Smoke tests pass → Deploy to production
All tests pass → Tag release

Block deployments:

Critical test fails → Stop deployment
Pass rate drops → Alert and pause
Regression detected → Rollback

Custom Notifications

Beyond built-in integrations:

Send to Discord, Telegram, or custom chat
SMS alerts for critical failures
Email to custom addresses
Push notifications to mobile apps

Data Sync

Keep systems in sync:

Push test results to data warehouse
Update status in project management tools
Log events in monitoring systems
Archive results to long-term storage

Workflow Automation

Trigger automated workflows:

Test fails → Create ticket in your system
Discovery completes → Generate documentation
New test created → Run code review
Team member joins → Provision access

Setting Up Webhooks

Prerequisites

HTTP endpoint that accepts POST requests
Returns 200 status code on success
Admin or owner role in BugBrain
Available on all plans (limits vary)

Step 1: Prepare Your Endpoint

Your webhook endpoint should:

Accept POST requests:

POST /webhooks/bugbrain HTTP/1.1
Host: api.yourapp.com
Content-Type: application/json
X-BugBrain-Signature: sha256=abc123...
X-BugBrain-Event: test.execution.failed
X-BugBrain-Delivery: uuid-1234
 
{
  "event": "test.execution.failed",
  "timestamp": "2026-02-19T10:30:00Z",
  "organization_id": "org_123",
  "data": {
    // event-specific data
  }
}

Respond quickly:

Return 200 status code within 5 seconds
Process events asynchronously if needed
Don’t perform long operations in webhook handler

Verify signatures:

Check X-BugBrain-Signature header
Prevents unauthorized requests
See “Security” section below

Step 2: Register Webhook in BugBrain

Go to Settings → Integrations → Webhooks
Click “Add Webhook”
Fill in details:
- Name: Descriptive name (e.g., “CI/CD Pipeline”)
- URL: Your endpoint URL
- Secret: Random string for signature verification
- Events: Choose which events to receive
Click “Create”
BugBrain sends test event to verify

Generate secure secret: Use a long, random string. Example: openssl rand -base64 32

Step 3: Test the Webhook

Click “Send Test Event” next to your webhook
Check your endpoint received the request
Verify signature validation works
Review payload format
Adjust your handler if needed

Available Events

Test Execution Events

test.execution.started

Test execution begins
Includes test details, project, priority

test.execution.completed

Test execution finishes (any status)
Includes result, duration, status

test.execution.passed

Test execution succeeded
Includes execution details

test.execution.failed

Test execution failed
Includes error message, screenshots, logs

test.execution.timeout

Test execution timed out
Includes partial results

Test Case Events

test.case.created

New test case created
Includes test details, steps

test.case.updated

Test case modified
Includes changes made

test.case.deleted

Test case removed
Includes test ID and name

Test Plan Events

test.plan.started

Test plan execution begins
Includes plan details, tests included

test.plan.completed

Test plan finishes
Includes summary, pass/fail counts

test.plan.scheduled

Scheduled test plan triggered
Includes schedule details

Discovery Events

discovery.session.started

Discovery session begins
Includes target URL, configuration

discovery.session.completed

Discovery session finishes
Includes pages found, flows detected

discovery.flow.detected

User flow identified
Includes flow details, pages involved

Organization Events

organization.member.added

New team member joined
Includes user details, role

organization.member.removed

Team member removed
Includes user ID

organization.quota.warning

Approaching quota limit
Includes quota type, usage percentage

organization.quota.exceeded

Quota limit reached
Includes quota type

Billing Events

billing.subscription.updated

Plan changed
Includes old and new plan

billing.subscription.cancelled

Subscription cancelled
Includes cancellation date

billing.payment.succeeded

Payment processed successfully
Includes invoice details

billing.payment.failed

Payment failed
Includes failure reason

Event Payload Format

Standard Structure

All webhook events follow this structure:

{
  "event": "event.type.name",
  "timestamp": "2026-02-19T10:30:00Z",
  "organization_id": "org_abc123",
  "webhook_id": "webhook_xyz789",
  "delivery_id": "uuid-1234-5678",
  "data": {
    // Event-specific data here
  }
}

Example: Test Execution Failed

{
  "event": "test.execution.failed",
  "timestamp": "2026-02-19T10:30:45Z",
  "organization_id": "org_abc123",
  "webhook_id": "webhook_xyz789",
  "delivery_id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
  "data": {
    "execution": {
      "id": "exec_123",
      "test_case_id": "test_456",
      "test_case_name": "Login with valid credentials",
      "project_id": "proj_789",
      "project_name": "Production App",
      "status": "failed",
      "priority": "high",
      "duration_ms": 12500,
      "started_at": "2026-02-19T10:30:32Z",
      "completed_at": "2026-02-19T10:30:45Z",
      "error": {
        "message": "Element not found: button#login",
        "type": "ElementNotFoundError",
        "step": 3,
        "step_description": "Click login button"
      },
      "screenshots": [
        "https://storage.bugbrain.tech/screenshots/exec_123_failure.png"
      ],
      "url": "https://app.bugbrain.tech/executions/exec_123"
    },
    "environment": {
      "browser": "chromium",
      "viewport": "1920x1080",
      "url": "https://app.example.com/login"
    }
  }
}

Example: Test Plan Completed

{
  "event": "test.plan.completed",
  "timestamp": "2026-02-19T11:00:00Z",
  "organization_id": "org_abc123",
  "webhook_id": "webhook_xyz789",
  "delivery_id": "a1b2c3d4-e5f6-7890-abcd-ef0987654321",
  "data": {
    "test_plan": {
      "id": "plan_555",
      "name": "Smoke Tests",
      "project_id": "proj_789",
      "project_name": "Production App",
      "started_at": "2026-02-19T10:45:00Z",
      "completed_at": "2026-02-19T11:00:00Z",
      "duration_ms": 900000,
      "summary": {
        "total": 25,
        "passed": 23,
        "failed": 2,
        "skipped": 0,
        "pass_rate": 92
      },
      "failed_tests": [
        {
          "id": "exec_123",
          "name": "Login with valid credentials",
          "error": "Element not found"
        },
        {
          "id": "exec_124",
          "name": "Checkout flow",
          "error": "Timeout after 60s"
        }
      ],
      "url": "https://app.bugbrain.tech/test-plans/plan_555"
    }
  }
}

Security

Signature Verification

Verify webhook requests are from BugBrain:

How signatures work:

BugBrain generates HMAC-SHA256 signature
Uses your webhook secret as key
Signs the request body
Sends in X-BugBrain-Signature header

Verify in your code:

// Node.js example
const crypto = require('crypto');
 
function verifyWebhook(req, secret) {
  const signature = req.headers['x-bugbrain-signature'];
  const hash = crypto
    .createHmac('sha256', secret)
    .update(req.rawBody)
    .digest('hex');
 
  const expectedSignature = `sha256=${hash}`;
 
  // Use timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
 
app.post('/webhooks/bugbrain', (req, res) => {
  if (!verifyWebhook(req, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
 
  // Process webhook
  const event = req.body;
  console.log('Received event:', event.event);
 
  res.json({ received: true });
});

# Python example
import hmac
import hashlib
 
def verify_webhook(request, secret):
    signature = request.headers.get('X-BugBrain-Signature', '')
    body = request.get_data()
 
    hash_object = hmac.new(
        secret.encode('utf-8'),
        body,
        hashlib.sha256
    )
    expected_signature = f"sha256={hash_object.hexdigest()}"
 
    return hmac.compare_digest(signature, expected_signature)
 
@app.route('/webhooks/bugbrain', methods=['POST'])
def handle_webhook():
    if not verify_webhook(request, os.environ['WEBHOOK_SECRET']):
        return jsonify({'error': 'Invalid signature'}), 401
 
    event = request.json
    print(f"Received event: {event['event']}")
 
    return jsonify({'received': True})

⚠️

Always verify signatures! Without verification, anyone can send fake events to your endpoint.

IP Allowlisting (Optional)

Restrict webhook requests to BugBrain IP addresses:

BugBrain webhook IPs:

34.123.45.0/24
52.202.45.0/24

Configure your firewall or application to only accept POST requests to your webhook endpoint from these IPs.

HTTPS Required

Webhook URLs must use HTTPS (not HTTP)
Protects data in transit
Required for production webhooks
HTTP allowed for local development only

Delivery & Retries

Delivery Guarantees

At-least-once delivery:

Events delivered at least once
May be delivered multiple times in failure scenarios
Design your endpoint to be idempotent

Timeout:

Webhook must respond within 5 seconds
Longer responses considered failed
Will trigger retry

Retry Logic

If delivery fails:

Retry schedule:

Immediately (attempt 1)
1 minute later (attempt 2)
5 minutes later (attempt 3)
15 minutes later (attempt 4)
1 hour later (attempt 5)
3 hours later (attempt 6)
6 hours later (attempt 7)

After 7 failed attempts:

Delivery marked as failed
Webhook may be automatically disabled
Admin notified via email

Successful response:

HTTP status 200-299
Any other status triggers retry

Monitoring Deliveries

View webhook delivery status:

Settings → Integrations → Webhooks
Click webhook name
View “Recent Deliveries”
See success/failure status
Inspect payloads and responses

Delivery details show:

Timestamp
Event type
HTTP status code
Response body
Response time
Retry attempts

Filtering Events

Event Filtering

Choose which events to receive:

Filter by event type:

Select specific events (e.g., only failures)
Reduces noise
Saves bandwidth

Filter by project:

Only events from specific projects
Different webhooks for different projects

Filter by priority:

Only critical and high priority test events
Ignore low-priority events

Configure filters:

Edit webhook
Click “Configure Filters”
Choose events, projects, priorities
Save

Conditional Webhooks

Send webhooks based on conditions:

Examples:

Only send if test failed 3+ times
Only send during business hours
Only send if pass rate < 80%
Only send for production environment

Configure:

Edit webhook → Advanced
Add conditional rules
Use expression builder
Test conditions
Save

💡

Pro Feature: Conditional webhooks and advanced filtering available on Pro plan.

Rate Limiting

Delivery Rate Limits

Per webhook limits:

100 events per minute
10,000 events per day
Excess events queued

Global limits:

1,000 events per minute per organization
100,000 events per day per organization

If limit exceeded:

Events queued for delivery
Delivered when rate limit resets
Webhook temporarily throttled

Avoiding Rate Limits

Best practices:

Use event filtering to reduce volume
Batch related events if possible
Use conditional webhooks
Consider consolidating webhooks

Testing & Debugging

Test Event

Send sample event to test:

Settings → Webhooks → Your Webhook
Click “Send Test Event”
Choose event type
Review payload
Send

Webhook Logs

View detailed logs:

Settings → Webhooks → Your Webhook
Click “Logs” tab
See all deliveries (last 30 days)
Filter by status, event type
Inspect request/response

Replay Events

Resend failed events:

Go to Webhook Logs
Find failed delivery
Click “Retry”
Event sent again immediately

Local Development

Test webhooks locally:

Use ngrok or similar:

# Start your local server
npm start
 
# In another terminal, expose it
ngrok http 3000
 
# Use ngrok URL in BugBrain webhook settings
https://abc123.ngrok.io/webhooks/bugbrain

Or use webhook testing services:

webhook.site
requestbin.com
hookbin.com

Example Implementations

CI/CD Pipeline Trigger

// Express.js webhook handler
app.post('/webhooks/bugbrain', async (req, res) => {
  // Verify signature
  if (!verifyWebhook(req, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
 
  const event = req.body;
 
  // Respond quickly
  res.json({ received: true });
 
  // Process asynchronously
  if (event.event === 'test.plan.completed') {
    const passRate = event.data.test_plan.summary.pass_rate;
 
    if (passRate >= 95) {
      // All tests passed, trigger deployment
      await triggerDeployment({
        environment: 'production',
        version: event.data.test_plan.version
      });
 
      console.log('✅ Deployment triggered');
    } else {
      // Tests failed, alert team
      await sendSlackAlert({
        message: `⚠️ Deployment blocked: ${passRate}% pass rate`,
        channel: '#alerts'
      });
 
      console.log('❌ Deployment blocked');
    }
  }
});

Custom Notification System

# Flask webhook handler
@app.route('/webhooks/bugbrain', methods=['POST'])
def handle_bugbrain_webhook():
    # Verify signature
    if not verify_webhook(request, WEBHOOK_SECRET):
        return jsonify({'error': 'Invalid signature'}), 401
 
    event = request.json
 
    # Respond quickly
    response = jsonify({'received': True})
 
    # Process asynchronously
    if event['event'] == 'test.execution.failed':
        test_data = event['data']['execution']
 
        # Send to Discord
        send_discord_message(
            webhook_url=DISCORD_WEBHOOK,
            content=f"🚨 Test Failed: {test_data['test_case_name']}",
            embed={
                'title': test_data['test_case_name'],
                'description': test_data['error']['message'],
                'color': 0xFF0000,
                'url': test_data['url']
            }
        )
 
    return response

Data Warehouse Sync

// Sync test results to data warehouse
async function handleTestCompleted(event) {
  const execution = event.data.execution;
 
  await database.query(`
    INSERT INTO test_executions (
      id, test_case_id, project_id, status,
      duration_ms, error_message, timestamp
    ) VALUES ($1, $2, $3, $4, $5, $6, $7)
  `, [
    execution.id,
    execution.test_case_id,
    execution.project_id,
    execution.status,
    execution.duration_ms,
    execution.error?.message,
    event.timestamp
  ]);
 
  console.log('✅ Synced to data warehouse');
}

Best Practices

💡

1. Always Verify Signatures Never process webhooks without verifying the signature. This prevents unauthorized requests.

2. Respond Quickly Return 200 status within 5 seconds. Process events asynchronously if needed.

3. Handle Duplicates Design endpoints to be idempotent. Same event delivered twice should have same effect as once.

4. Log Everything Log all webhook deliveries for debugging and monitoring.

5. Use Event Filtering Only subscribe to events you need to reduce noise and improve performance.

6. Monitor Failures Set up alerts for webhook delivery failures so you know when something breaks.

7. Rotate Secrets Periodically regenerate webhook secrets for security.

Troubleshooting

Webhooks Not Received

Check these:

Verify endpoint is accessible from internet
Ensure HTTPS certificate is valid
Check firewall/security group rules
Verify webhook is enabled in BugBrain
Review event filters

Test connectivity:

# Test from command line
curl -X POST https://your-endpoint.com/webhooks/bugbrain \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Signature Verification Fails

Common issues:

Using wrong secret
Not using raw request body
String encoding issues
Header not present

Debug:

Log the signature from header
Log your computed signature
Compare character by character
Check secret in BugBrain settings

Delivery Failures

“Connection timeout” error:

Endpoint not responding within 5 seconds
Process events asynchronously
Return 200 immediately

“SSL certificate error”:

Certificate expired or invalid
Use valid SSL certificate
Check certificate chain

Quota & Limits

Webhook limits by plan:

Feature	Starter	Growth	Pro
Webhooks	3	10	Unlimited
Events/day	1,000	10,000	100,000
Retries	3	7	7
Delivery History	7 days	30 days	90 days
Conditional Webhooks	❌	✅	✅
Advanced Filtering	❌	✅	✅

Next Steps

Set up Slack integration for quick setup
Configure Jira integration for issue tracking
Learn about notifications
Explore API documentation for building custom integrations

Trello