Webhooks

Configure outgoing webhooks to notify external systems when BambooSnow events occur.

Overview

Webhooks allow you to:

• Send notifications to external systems
• Trigger custom workflows
• Integrate with third-party tools
• Build custom dashboards

Setting Up Webhooks

Via Dashboard

1. Go to Settings > Webhooks
2. Click Add Webhook
3. Enter the endpoint URL
4. Select events to subscribe to
5. Click Create Webhook

Via API

curl -X POST https://api.bamboosnow.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://your-server.com/webhooks/bamboosnow",
    "events": ["agent.completed", "security.alert"],
    "secret": "your-webhook-secret"
  }'

Webhook Events

Agent Events

| Event | Description | |-------|-------------| | agent.started | Agent run started | | agent.completed | Agent run completed successfully | | agent.failed | Agent run failed | | agent.issues_found | Agent found issues |

Security Events

| Event | Description | |-------|-------------| | security.alert | New security vulnerability found | | security.resolved | Security issue resolved | | security.scan_completed | Security scan finished |

Approval Events

| Event | Description | |-------|-------------| | approval.requested | Approval needed for action | | approval.approved | Action was approved | | approval.rejected | Action was rejected |

Repository Events

| Event | Description | |-------|-------------| | repository.connected | New repository connected | | repository.disconnected | Repository disconnected | | repository.analyzed | Repository analysis completed |

Webhook Payload

All webhooks include a standard envelope:

{
  "id": "evt_abc123",
  "type": "agent.completed",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    // Event-specific data
  },
  "repository": {
    "id": "repo_xyz",
    "name": "owner/repo"
  }
}

Example: agent.completed

{
  "id": "evt_abc123",
  "type": "agent.completed",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "agent": {
      "id": "agent_123",
      "name": "code-reviewer",
      "template": "code-reviewer"
    },
    "run": {
      "id": "run_456",
      "status": "success",
      "duration_ms": 45000,
      "issues_found": 3
    },
    "pull_request": {
      "number": 123,
      "title": "Add user authentication",
      "url": "https://github.com/owner/repo/pull/123"
    },
    "results": {
      "errors": 0,
      "warnings": 2,
      "info": 1
    }
  }
}

Example: security.alert

{
  "id": "evt_def456",
  "type": "security.alert",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "vulnerability": {
      "id": "CVE-2024-1234",
      "severity": "high",
      "package": "lodash",
      "version": "4.17.20",
      "fixed_in": "4.17.21"
    },
    "affected_files": [
      "package.json",
      "package-lock.json"
    ],
    "recommendation": "Update lodash to version 4.17.21 or later"
  }
}

Signature Verification

Webhooks include a signature header for verification:

X-BambooSnow-Signature: sha256=abc123...

Verification Example (Node.js)

const crypto = require('crypto');

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

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

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

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

  // Process webhook
  handleEvent(req.body);
  res.status(200).send('OK');
});

Retry Policy

Failed webhook deliveries are retried:

| Attempt | Delay | |---------|-------| | 1 | Immediate | | 2 | 1 minute | | 3 | 5 minutes | | 4 | 30 minutes | | 5 | 2 hours |

After 5 failed attempts, the webhook is disabled.

Debugging Webhooks

Webhook Logs

View delivery attempts in the dashboard:

1. Go to Settings > Webhooks
2. Click on a webhook
3. View Recent Deliveries

Test Endpoint

Send a test event:

curl -X POST https://api.bamboosnow.com/v1/webhooks/{id}/test

Webhook.site

For development, use webhook.site:

1. Go to webhook.site
2. Copy your unique URL
3. Add it as a webhook endpoint
4. View incoming requests in real-time