Webhooks & Integrations

Receive real-time notifications about post publishing, analytics updates, and system events. Integrate Blackspace with your existing workflows and tools.

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., post published), 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 'post.published':
      handlePostPublished(event.data);
      break;
    case 'post.scheduled':
      handlePostScheduled(event.data);
      break;
    case 'analytics.updated':
      handleAnalyticsUpdated(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

Post Events

post.published

Triggered when a post is successfully published to one or more platforms.

{
  "type": "post.published",
  "timestamp": "2025-10-05T14:30:00Z",
  "data": {
    "post_id": "post_abc123",
    "platforms": ["instagram", "x"],
    "published_at": "2025-10-05T14:30:00Z",
    "urls": {
      "instagram": "https://instagram.com/p/abc123",
      "x": "https://x.com/user/status/456"
    }
  }
}
post.scheduled

Triggered when a post is scheduled for future publishing.

post.failed

Triggered when a post fails to publish due to an error.

post.deleted

Triggered when a post is deleted from the platform.

Analytics Events

analytics.updated

Triggered when analytics data is updated for a post (hourly).

{
  "type": "analytics.updated",
  "timestamp": "2025-10-05T15:00:00Z",
  "data": {
    "post_id": "post_abc123",
    "metrics": {
      "views": 5420,
      "likes": 312,
      "comments": 24,
      "shares": 45,
      "engagement_rate": 7.2
    },
    "platforms": {
      "instagram": { "views": 3200, "likes": 201 },
      "x": { "views": 2220, "likes": 111 }
    }
  }
}
analytics.milestone

Triggered when a post reaches a milestone (1K, 10K, 100K views, etc.).

Account Events

account.connected

Triggered when a new social account is connected.

account.disconnected

Triggered when a social account is disconnected.

account.token_expired

Triggered when OAuth token for a platform expires and needs renewal.

Third-Party Integrations

Connect Blackspace with your favorite tools and platforms using native integrations or Zapier.

Slack

Get notifications in Slack when posts are published or analytics milestones are reached.

Status: Coming Soon

Zapier

Connect Blackspace to 5,000+ apps with our Zapier integration for endless automation possibilities.

Status: Coming Soon

Google Sheets

Sync your analytics data to Google Sheets for custom reporting and analysis.

Status: Coming Soon

Discord

Receive webhook notifications in Discord channels for team collaboration.

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 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": "post.published"
  }'