Webhooks Documentation

Automate HTTP callbacks from Corgea to any external system

What are Webhooks?

Webhooks are automated HTTP callbacks that allow Corgea to send real-time notifications to your external systems when specific events occur. Instead of continuously polling our API to check for updates, webhooks push event data directly to your specified endpoint the moment something happens.

Key Benefits

• Real-time notifications - Receive instant updates when security issues are found, status changes occur, or scans complete
• Automation - Trigger workflows in external tools like Slack, Zapier, or custom applications
• Efficiency - No need to poll APIs - we push data to you when events happen
• Flexibility - Subscribe only to the events you care about and filter by project or status
• Reliability - Built-in retry logic and delivery tracking ensure your notifications get through

Supported Event Types

Corgea supports webhooks for the following events:

Issue Events:

• issue.status_changed - Triggered when an issue’s status is updated (e.g., open → fixed)
• issue.assigned - Triggered when an issue is assigned to a team member

Scan Events:

• scan.started - Triggered when a security scan begins
• scan.completed - Triggered when a scan finishes successfully
• scan.failed - Triggered when a scan encounters an error

---

How Webhooks Work

The Webhook Lifecycle

1. Event Occurs

   Something happens in Corgea (e.g., a scan completes, an issue status changes)

2. Webhook Triggered

   The system identifies all webhooks subscribed to that event type

3. Filtering Applied

   Project and status filters determine if the webhook should fire

4. Payload Built

   A standardized JSON payload is constructed with event details

5. HTTP POST Request

   The payload is sent to your webhook URL with security headers

6. Retry Logic

   If the request fails, automatic retries occur with exponential backoff

7. Delivery Logged

   All attempts are tracked in the delivery history for troubleshooting

Payload Structure

All webhook payloads follow a standardized structure:

webhook-payload.json

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "scan.completed",
  "timestamp": "2025-01-15T14:30:00.000Z",
  "data": {
    "company": "company-uuid",
    "scan_id": "scan-uuid",
    "project": {
      "id": "project-uuid",
      "name": "My Application"
    },
    "issues_found": 12,
    ...
  }
}

Security Features

HMAC Signature Verification

• When you provide a secret key, Corgea includes an X-Corgea-Signature header
• This header contains an HMAC-SHA256 hash of the payload
• Verify the signature to ensure the webhook came from Corgea

Custom Headers

• Include headers required by your endpoint (e.g., authentication tokens)
• Configure custom headers during webhook setup

HTTPS Required

• All webhook URLs must use HTTPS for secure transmission
• Non-HTTPS URLs will be rejected to protect sensitive data

Automatic Retry Logic

If webhook delivery fails, Corgea automatically retries with the following strategy:

• Initial attempt + 2 retries = 3 total attempts
• Exponential backoff: 2 seconds, 4 seconds between retries
• Timeout: 10 seconds per request
• Auto-pause: After 10 consecutive failures, the webhook is automatically paused

Headers Sent with Each Webhook

webhook-headers.txt

Content-Type: application/json
X-Corgea-Event: issue.status_changed
X-Corgea-Delivery: <delivery-uuid>
X-Corgea-Timestamp: <unix-timestamp>
X-Corgea-Signature: <hmac-signature> (if secret configured)
User-Agent: Corgea-Webhooks/1.0

---

Setting Up a Webhook

Prerequisites

Admin or integration management permissions in your Corgea account

A webhook endpoint URL that accepts POST requests

HTTPS endpoint (required for security)

Step-by-Step Setup

1. Navigate to Integrations

   • Go to your Corgea dashboard
   • Click on “Integrations” in the navigation menu
   • Select “Webhooks” or “Create New Webhook”

   
2. Configure Basic Settings

   

   • Name: Give your webhook a descriptive name (e.g., “Slack Notifications”, “Production Scan Alerts”)
   • Webhook URL: Enter your HTTPS endpoint URL
   • Type: Select the integration type:
     • Slack - For Slack webhook integrations
     • Zapier - For Zapier zaps
     • Other - For custom integrations
3. Subscribe to Events

   • Check the boxes for events you want to receive:
     • Issue Status Changed
     • Issue Assigned
     • Scan Started
     • Scan Completed
     • Scan Failed
   • You can select multiple events per webhook
4. Configure Filters (Optional)

   Project Filter

   • Leave empty to receive events from all projects
   • Select specific projects to only receive their events
   • Useful for routing different projects to different endpoints

   Status Change Filter (for issue.status_changed events)

   • Leave empty to receive all status changes
   • Select specific statuses (e.g., fixed, false_positive) to only receive those changes
   • Reduces noise by filtering out irrelevant status updates
5. Add Security (Optional but Recommended)

   Secret Key

   • Enter a random, secure string (minimum 32 characters recommended)
   • Corgea will include an HMAC signature in the X-Corgea-Signature header
   • Use this to verify webhook authenticity on your end

   Custom Headers

   • Add any headers your endpoint requires
   • Common examples: Authorization: Bearer <token>, X-API-Key: <key>
6. Test Your Webhook

   • Click “Test Webhook” to send a sample payload
   • Verify your endpoint receives and processes the test correctly
   • Check the response status and any error messages
7. Save and Activate

   • Click “Create Webhook” or “Save”
   • The webhook is now active and will start receiving events

Verifying Webhook Signatures

If you configured a secret key, verify the signature in your endpoint to ensure authenticity.

Python

verify-signature.py

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    """Verify Corgea webhook signature"""
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected_signature, signature)

# In your webhook handler:
if not verify_webhook_signature(request.body, request.headers['X-Corgea-Signature'], SECRET_KEY):
    return HttpResponse(status=403)  # Reject invalid signatures

---

Use Cases

1. Real-time Slack Notifications

Scenario: Notify your security team in Slack when high-severity issues are found

Setup:

• Create a Slack incoming webhook URL in your Slack workspace
• In Corgea, create a webhook with:
  • Type: Slack
  • URL: Your Slack webhook URL
  • Events: scan.completed
  • Project Filter: Critical production projects

Result: Your #security channel gets instant notifications when scans complete

---

2. Automated Ticketing for Critical Issues

Scenario: Automatically create tickets in Jira/Linear when critical issues are detected

Setup:

• Create a Zapier zap or custom endpoint that creates tickets
• In Corgea, create a webhook with:
  • Events: scan.completed, issue.status_changed
  • Status Filter: Only open status (to avoid duplicate tickets)
  • Project Filter: Production projects

Result: High/critical issues automatically become tickets in your project management tool

---

3. Risk Acceptance Workflow Integration

Scenario: Automatically document accepted risks in Jira or Linear when security issues are marked as “Accepted Risk”

Setup:

• Create an endpoint or Zapier integration that creates documentation tickets
• In Corgea, create a webhook with:
  • Events: issue.status_changed
  • Status Filter: Only accepted_risk status
  • Project Filter: All projects or specific high-compliance projects
• Configure the integration to:
  • Create a ticket documenting the risk acceptance
  • Include issue details (classification, file path, urgency)
  • Tag with “risk-acceptance” label
  • Assign to security lead for review

Result: Every accepted risk is automatically logged in your project management system with full context, creating an audit trail for compliance and risk management reviews

---

4. Custom Dashboard Integration

Scenario: Display real-time security metrics on your internal dashboard

Setup:

• Build an endpoint that receives webhook data and updates your dashboard
• In Corgea, create a webhook with:
  • Events: All scan and issue events
  • No filters (receive everything)

Result: Your dashboard shows live security scan results and issue trends

---

5. Multi-team Routing

Scenario: Route different project notifications to different teams

Setup:

• Create separate webhooks for each team:
  • Backend Team Webhook: Project filter = backend projects, Slack channel #backend-security
  • Frontend Team Webhook: Project filter = frontend projects, Slack channel #frontend-security
  • DevOps Team Webhook: Project filter = infrastructure projects, Slack channel #devops-security

Result: Each team only sees security issues relevant to their projects

---

6. Compliance Reporting

Scenario: Automatically log all security findings to a compliance system

Setup:

• Create an endpoint that writes to your compliance database
• In Corgea, create a webhook with:
  • Events: scan.completed
  • All projects
  • Store webhook delivery history for audit trail

Result: Complete audit trail of all security scans for compliance purposes

---

Troubleshooting

Viewing Webhook Delivery History

1. Navigate to Webhook History

   Navigate to Integrations → Webhooks

   
2. Access Delivery Log

   Click on History or Delivery Log

3. Review Delivery Details

   

   View all webhook delivery attempts with:

   • Event type and timestamp
   • HTTP status code
   • Request/response details
   • Error messages (if any)
   • Retry attempts

Common Issues and Solutions

Webhook Not Receiving Events

Possible Causes:

• Webhook is paused or inactive
• Event subscriptions not configured
• Project/status filters excluding events
• Endpoint not returning 2xx status codes

Solutions:

1. Check webhook status - ensure it’s active (not paused)
2. Verify event subscriptions are selected
3. Review filters - temporarily remove filters to test
4. Check your endpoint logs for incoming requests
5. Test the webhook using the “Test Webhook” button

Webhook Automatically Paused

Cause: 10 consecutive delivery failures

Solutions:

1. Check the delivery history for error details
2. Verify your endpoint URL is correct and accessible
3. Ensure your endpoint returns 2xx status codes
4. Check for firewall/security rules blocking Corgea’s requests
5. Fix the underlying issue, then manually re-activate the webhook
6. Use “Test Webhook” to verify it’s working before re-enabling

Receiving Too Many Webhook Calls

Solutions:

1. Use Status Filters: For issue.status_changed, filter to only statuses you care about (e.g., only fixed and false_positive)
2. Use Project Filters: Only subscribe to specific critical projects
3. Reduce Event Subscriptions: Unsubscribe from events you don’t need
4. Implement Rate Limiting: On your endpoint, implement rate limiting or queuing

Signature Verification Failing

Possible Causes:

• Wrong secret key
• Incorrect signature verification logic
• Character encoding issues

Solutions:

1. Verify you’re using the exact secret key from Corgea
2. Ensure you’re using HMAC-SHA256 algorithm
3. Use the raw request body (not parsed JSON) for verification
4. Check for UTF-8 encoding on both sides
5. Use hmac.compare_digest() (Python) or crypto.timingSafeEqual() (Node.js) for timing-safe comparison

Log both the received signature and your computed signature to compare

Endpoint Timing Out

Cause: Your endpoint takes longer than 10 seconds to respond

Solutions:

1. Acknowledge Immediately: Return 200 OK immediately, then process asynchronously
2. Use a Queue: Add webhook payloads to a queue for background processing
3. Optimize Processing: Speed up your webhook handler logic
4. Increase Resources: Scale up your endpoint infrastructure

Best Practice Pattern:

webhook-handler.py

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    payload = request.json

    # Immediately acknowledge receipt
    queue.add(process_webhook, payload)

    # Return quickly
    return '', 200

def process_webhook(payload):
    # Do time-consuming work here
    ...

Duplicate Events

Possible Causes:

• Multiple webhooks subscribed to same event
• Retry logic triggering after delayed success

Solutions:

1. Check for duplicate webhook configurations
2. Use event_id field for idempotency - store processed event IDs and skip duplicates
3. Implement idempotency keys in your endpoint

Idempotency Pattern:

idempotency.py

processed_events = set()  # Or use Redis/database

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    event_id = request.json['event_id']

    if event_id in processed_events:
        return '', 200  # Already processed

    # Process event...
    processed_events.add(event_id)
    return '', 200

Missing Data in Payload

Solutions:

1. Check the webhook delivery history for the full payload
2. Some fields may be null if data doesn’t exist (e.g., unassigned issues)
3. Implement null checks in your handler code
4. Reference the event-specific payload structure in the delivery history

Getting Webhook Statistics

View performance metrics for your webhooks:

1. Navigate to Integrations → Webhooks
2. View each webhook’s statistics:
   • Total Deliveries: Total number of webhook calls
   • Successful Deliveries: Calls that returned 2xx
   • Failed Deliveries: Calls that failed or timed out
   • Success Rate: Percentage of successful deliveries
   • Consecutive Failures: Current failure streak
   • Last Triggered: When the webhook last fired

---

Manual Retry

If a webhook delivery failed, you can manually retry it:

1. Go to Integrations → Webhooks → History
2. Find the failed delivery
3. Click Retry
4. A new delivery attempt will be created and sent immediately

---

Exporting Delivery History

For compliance or debugging, export webhook delivery history:

1. Navigate to Integrations → Webhooks → History
2. Apply filters (date range, event type, status, webhook)
3. Click Export to download CSV
4. Use the export for:
   • Compliance audits
   • Performance analysis
   • Debugging patterns
   • Issue resolution tracking

---

Testing Tips

Before Going Live

1. Use webhook.site or RequestBin to inspect payloads
2. Test with low-volume projects first
3. Monitor delivery success rate for the first few days
4. Set up alerting for webhook failures in your own system

Debug Checklist

• Webhook URL is correct and accessible
• Endpoint returns 2xx status code within 10 seconds
• Firewall allows Corgea’s requests
• Event subscriptions are selected
• Filters are configured correctly (or removed for testing)
• Signature verification works (if using secret)
• Webhook is active (not paused)

---

Payload Examples

Issue Status Changed

issue-status-changed.json

{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_type": "issue.status_changed",
  "timestamp": "2025-01-15T14:30:00.000Z",
  "data": {
    "company": "comp-uuid-1234",
    "issue_id": "issue-uuid-5678",
    "classification": "SQL Injection",
    "urgency": "HI",
    "status": "fixed",
    "previous_status": "open",
    "file_path": "src/controllers/user.py",
    "line_num": 45,
    "project": {
      "id": "proj-uuid-9012",
      "name": "Production API"
    },
    "scan_id": "scan-uuid-3456",
    "url": "https://app.corgea.com/issue/issue-uuid-5678/"
  }
}

---

FAQ

Can I use the same webhook URL for multiple event types?

Yes! Your endpoint will receive an X-Corgea-Event header and event_type field to identify the event.

How many webhooks can I create?

There’s no hard limit, but we recommend organizing by purpose (e.g., one per team or tool).

What happens if my endpoint is down?

Corgea will retry 3 times with exponential backoff. After 10 consecutive failures, the webhook auto-pauses.

Can I test webhooks without triggering real events?

Yes! Use the “Test Webhook” button to send a sample payload without waiting for real events.

Do webhooks support authentication?

Yes! Use custom headers to include authentication tokens, or use HMAC signature verification.

Can I filter webhooks to specific branches?

Not directly, but you can filter by project. You can also filter on the received payload in your endpoint.

Are webhook payloads encrypted?

Payloads are sent over HTTPS (TLS), providing encryption in transit. Use HMAC signatures for verification.

How long are webhook delivery logs kept?

Delivery logs are retained for compliance and debugging. Check with your plan for specific retention periods.

Can I retry a webhook manually?

Yes! Go to the webhook delivery history and click “Retry” on any failed delivery.

What IP addresses does Corgea send webhooks from?

Contact support for the current list of IP addresses to whitelist in your firewall.

---

Questions or issues? Contact Corgea Support