Webhooks & Integrations

Receive real-time notifications about agent runs, failures, and usage events. Integrate blackspace.ai with your existing backend workflows.

What are Webhooks?

Webhooks allow you to receive HTTP callbacks when specific events occur in your Blackspace account. Instead of polling our API for updates, we'll push notifications to your server in real-time.

How Webhooks Work

  1. You configure a webhook URL in your Blackspace settings
  2. When an event occurs (e.g., run completed), we send an HTTP POST to your URL
  3. Your server processes the event and responds with a 200 status code
  4. If we don't receive a 200, we'll retry with exponential backoff

Setting Up Webhooks

1. Create Webhook Endpoint

Set up an endpoint on your server to receive webhook events:

// Example using Node.js/Express
app.post('/webhooks/blackspace', (req, res) => {
  const event = req.body;
  
  // Verify webhook signature
  const signature = req.headers['x-blackspace-signature'];
  if (!verifySignature(signature, req.body)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the event
  switch (event.type) {
    case 'run.completed':
      handleRunCompleted(event.data);
      break;
    case 'run.failed':
      handleRunFailed(event.data);
      break;
    case 'usage.threshold_reached':
      handleUsageAlert(event.data);
      break;
  }
  
  // Acknowledge receipt
  res.status(200).json({ received: true });
});

2. Configure Webhook in Settings

Add your webhook URL in the Blackspace dashboard:

  1. Navigate to Settings → Webhooks
  2. Click "Add Webhook Endpoint"
  3. Enter your webhook URL (must be HTTPS)
  4. Select events you want to receive
  5. Save and test your webhook

3. Verify Webhook Signatures

Always verify webhook signatures to ensure requests come from Blackspace:

import crypto from 'crypto';

function verifySignature(signature, payload) {
  const secret = process.env.BLACKSPACE_WEBHOOK_SECRET;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Event Types

Run Events

run.completed

Triggered when an agent run completes successfully.

{
  "type": "run.completed",
  "timestamp": "2025-10-05T14:30:00Z",
  "data": {
    "run_id": "run_abc123",
    "agent_slug": "research-briefer",
    "status": "completed",
    "duration_ms": 2140
  }
}
run.failed

Triggered when a run fails validation or execution.

run.queued

Triggered when a run enters queue state before execution.

Usage Events

usage.threshold_reached

Triggered when account usage crosses a configured threshold.

{
  "type": "usage.threshold_reached",
  "timestamp": "2025-10-05T15:00:00Z",
  "data": {
    "plan": "Starter",
    "runs_used": 180,
    "runs_limit": 200,
    "percent_used": 90
  }
}
usage.reset

Triggered at billing-cycle reset when monthly usage returns to zero.

Key Events

api_key.created

Triggered when a new API key is created.

api_key.revoked

Triggered when an API key is revoked.

api_key.expiring_soon

Triggered before key expiration to allow safe rotation.

Third-Party Integrations

Connect blackspace.ai with your favorite tools using webhooks or middleware services.

Slack

Notify channels when key runs complete, fail, or hit usage thresholds.

Status: Coming Soon

Zapier

Connect blackspace.ai to 5,000+ apps for internal automations and alerts.

Status: Coming Soon

Google Sheets

Sync run metadata and usage exports to Sheets for custom reporting.

Status: Coming Soon

Discord

Receive webhook notifications in Discord channels for async team ops.

Status: Coming Soon

Best Practices

Do

  • Respond quickly (within 5 seconds)
  • Validate webhook signatures
  • Handle events idempotently
  • Use HTTPS for webhook URLs
  • Log all webhook events
  • Implement retry logic for failures

Don't

  • Process webhooks synchronously
  • Expose webhook endpoints publicly
  • Skip signature verification
  • Store sensitive data in webhook URLs
  • Use HTTP instead of HTTPS
  • Block the response while processing

Testing Webhooks

Test your webhook integration using the test button in the blackspace.ai dashboard or by sending sample events:

curl -X POST https://blackspace.ai/api/v1/webhooks/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_id": "webhook_123",
            "event_type": "run.completed"
  }'