Skip to main content

Overview

Configure webhooks to receive real-time notifications when events occur in CodeWolf, enabling custom integrations and automated workflows.

Prerequisites

  • HTTPS endpoint to receive webhooks
  • CodeWolf account

Setup

1

Create webhook endpoint

Set up an HTTPS endpoint that can receive POST requests from CodeWolf.Your endpoint should:
  • Accept POST requests
  • Return a 2xx status code
  • Process requests within 10 seconds
Webhooks must use HTTPS. HTTP endpoints are not supported for security reasons.
2

Configure webhook in CodeWolf

Go to CodeWolf dashboard > Integrations > Webhooks.Click Add Webhook and enter:
  • URL: Your HTTPS endpoint
  • Secret: A secret key for signature verification
  • Events: Select which events to receive
3

Verify webhook

CodeWolf will send a test payload to verify your endpoint.
Respond with a 200 status code to confirm the webhook is working.

Event types

Subscribe to these CodeWolf events:

Code analysis

  • code.scan.completed: Code analysis finished
  • code.quality.changed: Quality score changed
  • code.complexity.increased: Complexity threshold exceeded

Security

  • security.vulnerability.detected: New vulnerability found
  • security.scan.completed: Security scan finished
  • security.issue.resolved: Security issue fixed

Deployments

  • deployment.started: Deployment initiated
  • deployment.completed: Deployment finished
  • deployment.failed: Deployment failed

Pull requests

  • pr.opened: Pull request created
  • pr.updated: Pull request updated
  • pr.merged: Pull request merged
  • pr.review.completed: Code review finished

Alerts

  • alert.triggered: Alert condition met
  • alert.resolved: Alert condition resolved

Payload structure

All webhook payloads follow this structure:
{
  "event": "security.vulnerability.detected",
  "timestamp": "2026-01-26T17:00:00Z",
  "id": "evt_1234567890",
  "data": {
    "repository": "myorg/myapp",
    "branch": "main",
    "vulnerability": {
      "id": "CVE-2024-1234",
      "severity": "high",
      "title": "SQL Injection vulnerability",
      "file": "src/database.js",
      "line": 42,
      "description": "User input not properly sanitized",
      "remediation": "Use parameterized queries"
    }
  }
}

Signature verification

Verify webhook authenticity using the signature:
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhooks/codewolf', (req, res) => {
  const signature = req.headers['x-codewolf-signature'];
  const isValid = verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  console.log('Received event:', req.body.event);
  res.status(200).send('OK');
});

Retry policy

CodeWolf retries failed webhook deliveries:
  • Retry attempts: Up to 5 retries
  • Backoff: Exponential backoff (1s, 2s, 4s, 8s, 16s)
  • Timeout: 10 seconds per attempt
  • Success codes: 200-299
If all retry attempts fail, the event is marked as failed and logged in your webhook dashboard.

Filtering events

Filter events by criteria to reduce noise:
{
  "url": "https://api.example.com/webhooks",
  "events": ["security.vulnerability.detected"],
  "filters": {
    "severity": ["high", "critical"],
    "repository": ["myorg/important-app"]
  }
}

Testing webhooks

Test your webhook endpoint with sample payloads:
  1. Go to Integrations > Webhooks
  2. Select your webhook
  3. Click Send Test Event
  4. Choose an event type
  5. View the delivery response

Monitoring

Track webhook delivery status:
  • Delivery logs: View all webhook attempts
  • Success rate: Percentage of successful deliveries
  • Response times: Endpoint latency
  • Failed deliveries: Events that need attention

Best practices

Do:
  • Verify webhook signatures
  • Process webhooks asynchronously
  • Return 2xx status codes quickly
  • Log all webhook events
  • Implement idempotency
  • Use HTTPS endpoints
Don’t:
  • Perform long-running operations synchronously
  • Expose webhook URLs publicly
  • Ignore signature verification
  • Use HTTP (non-secure) endpoints
  • Block on external API calls

Troubleshooting

  • Verify your endpoint is accessible from the internet
  • Check firewall rules allow incoming HTTPS traffic
  • Ensure your endpoint returns 2xx status codes
  • Review webhook logs in CodeWolf dashboard
  • Confirm you’re using the correct secret
  • Verify payload is not modified before verification
  • Check that you’re using the raw request body
  • Ensure consistent JSON serialization
  • Implement idempotency using the event ID
  • Store processed event IDs to prevent duplicates
  • Use database constraints or caching