Skip to main content

Webhooks Integration

Configure custom webhooks to integrate BlackTide with any service. Send alerts to your own endpoints, CI/CD pipelines, or custom notification systems.

What are Webhooks?

Webhooks are HTTP callbacks that BlackTide sends to your endpoints when monitors change state. Use webhooks to:

  • Integrate with custom internal tools
  • Trigger CI/CD pipelines on failures
  • Send alerts to unsupported platforms
  • Log incidents to custom databases
  • Automate remediation workflows

Configuration

Step 1: Create Webhook Channel

  1. Log in to BlackTide
  2. Navigate to Alerts → Alert Channels
  3. Click New Channel
  4. Select Webhook
  5. Fill in configuration:
    • Name: Custom Integration
    • URL: Your endpoint URL
    • Method: POST (recommended)
    • Headers: Authorization, Content-Type, etc.
    • Timeout: 30 seconds (default)
  6. Click Test Webhook
  7. Verify payload received at your endpoint
  8. Save the channel

Configuration Example

{
  "type": "webhook",
  "name": "Internal API",
  "url": "https://api.example.com/webhooks/blacktide",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
    "X-Custom-Header": "blacktide-alerts"
  },
  "timeout": 30,
  "retryOnFailure": true,
  "maxRetries": 3
}

Payload Format

Monitor Down Event

When a monitor fails, BlackTide sends:

{
  "event": "monitor.down",
  "timestamp": "2026-02-13T10:30:00Z",
  "monitor": {
    "id": "mon_abc123",
    "name": "Production API",
    "type": "http",
    "url": "https://api.example.com/health",
    "status": "down"
  },
  "incident": {
    "id": "inc_xyz789",
    "severity": "critical",
    "consecutiveFailures": 3,
    "lastError": "Connection timeout after 10s",
    "downtime": 0
  },
  "links": {
    "monitor": "https://blacktide.xyz/monitors/mon_abc123",
    "incident": "https://blacktide.xyz/incidents/inc_xyz789"
  }
}

Monitor Up Event

When a monitor recovers:

{
  "event": "monitor.up",
  "timestamp": "2026-02-13T10:38:42Z",
  "monitor": {
    "id": "mon_abc123",
    "name": "Production API",
    "type": "http",
    "url": "https://api.example.com/health",
    "status": "up"
  },
  "incident": {
    "id": "inc_xyz789",
    "severity": "critical",
    "downtimeSeconds": 522,
    "downtimeFormatted": "8 minutes 42 seconds"
  },
  "links": {
    "monitor": "https://blacktide.xyz/monitors/mon_abc123",
    "incident": "https://blacktide.xyz/incidents/inc_xyz789"
  }
}

Web3 Alert Event

For Web3 monitors (gas price, wallet, etc.):

{
  "event": "web3.gas.alert",
  "timestamp": "2026-02-13T10:45:00Z",
  "monitor": {
    "id": "mon_web3_gas",
    "name": "Ethereum Gas Price",
    "type": "gas_price",
    "chain": "ethereum"
  },
  "alert": {
    "type": "high_gas",
    "currentGwei": 75,
    "thresholdGwei": 50,
    "message": "Gas price above threshold"
  },
  "links": {
    "monitor": "https://blacktide.xyz/monitors/mon_web3_gas"
  }
}

Authentication Methods

Bearer Token

{
  "headers": {
    "Authorization": "Bearer YOUR_SECRET_TOKEN"
  }
}

API Key

{
  "headers": {
    "X-API-Key": "YOUR_API_KEY"
  }
}

Basic Auth

{
  "headers": {
    "Authorization": "Basic base64(username:password)"
  }
}

Custom Signature

BlackTide can sign webhook payloads with HMAC-SHA256:

{
  "signatureHeader": "X-BlackTide-Signature",
  "signingSecret": "YOUR_WEBHOOK_SECRET"
}

// Verify signature in your endpoint:
const crypto = require('crypto');
const signature = req.headers['x-blacktide-signature'];
const body = JSON.stringify(req.body);
const hmac = crypto.createHmac('sha256', 'YOUR_WEBHOOK_SECRET');
const expectedSignature = hmac.update(body).digest('hex');

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

Retry Logic

BlackTide automatically retries failed webhooks with exponential backoff:

  • Retry 1: After 1 second
  • Retry 2: After 5 seconds
  • Retry 3: After 30 seconds

Webhooks are considered failed if:

  • HTTP status code is not 2xx
  • Request times out (default 30s)
  • Connection error occurs

Use Cases

1. Trigger CI/CD Pipeline

# Webhook triggers GitHub Actions workflow
POST https://api.github.com/repos/user/repo/dispatches
{
  "event_type": "blacktide_alert",
  "client_payload": {
    "monitor_id": "mon_abc123",
    "status": "down"
  }
}

2. Log to Custom Database

// Express.js endpoint example
app.post('/webhooks/blacktide', async (req, res) => {
  const { event, monitor, incident } = req.body;
  
  await db.incidents.create({
    monitor_id: monitor.id,
    monitor_name: monitor.name,
    event_type: event,
    severity: incident.severity,
    timestamp: new Date()
  });
  
  res.status(200).send('OK');
});

3. Send to Microsoft Teams

# Webhook URL: MS Teams Incoming Webhook
# Transform BlackTide payload to Teams format

{
  "@type": "MessageCard",
  "summary": "Monitor Alert",
  "themeColor": "FF0000",
  "title": "🚨 Production API Down",
  "sections": [{
    "facts": [
      {"name": "Monitor", "value": "Production API"},
      {"name": "Status", "value": "Down"},
      {"name": "Failures", "value": "3 consecutive"}
    ]
  }],
  "potentialAction": [{
    "@type": "OpenUri",
    "name": "View Monitor",
    "targets": [{
      "os": "default",
      "uri": "https://blacktide.xyz/monitors/mon_abc123"
    }]
  }]
}

4. Auto-Remediation

// Automatically restart service when monitor fails
app.post('/webhooks/auto-remediate', async (req, res) => {
  const { event, monitor } = req.body;
  
  if (event === 'monitor.down' && monitor.name === 'API Server') {
    // Restart service via PM2/systemd
    await exec('pm2 restart api-server');
    
    // Log remediation action
    await db.logs.create({
      action: 'auto_restart',
      monitor_id: monitor.id,
      timestamp: new Date()
    });
  }
  
  res.status(200).send('OK');
});

Best Practices

1. Validate Signatures

Always verify webhook signatures to prevent spoofing:

  • Use HMAC-SHA256 signing
  • Store signing secret securely (environment variables)
  • Reject requests with invalid signatures

2. Handle Retries Idempotently

Your endpoint may receive the same event multiple times:

  • Use event IDs to deduplicate
  • Store processed event IDs in cache/database
  • Return 200 OK even if already processed

3. Respond Quickly

Webhook endpoints should respond within 30 seconds:

  • Process payload asynchronously (queue)
  • Return 200 OK immediately
  • Handle heavy processing in background jobs

4. Monitor Your Webhooks

Track webhook health:

  • Log all incoming webhooks
  • Alert on high failure rates
  • Monitor response times

Troubleshooting

Webhooks Not Arriving

Possible Causes:

  • Endpoint URL is incorrect or not accessible
  • Firewall blocking BlackTide IPs
  • Endpoint returning non-2xx status code
  • Request timing out

Solution:

  1. Verify endpoint URL is publicly accessible
  2. Test with curl from external server
  3. Check firewall/security group rules
  4. Ensure endpoint responds within 30 seconds
  5. Check BlackTide webhook delivery logs

Webhooks Failing

Solution:

  • Check endpoint returns 200-299 status code
  • Verify authentication headers are correct
  • Increase timeout if processing takes longer
  • Check endpoint error logs for details

Security Considerations

  • Use HTTPS: Always use secure endpoints (https://)
  • Verify Signatures: Prevent unauthorized webhook calls
  • Whitelist IPs: Only allow BlackTide server IPs (optional)
  • Rate Limiting: Protect endpoint from abuse
  • Secrets Management: Store tokens/keys securely

Next Steps