ConnectHub Developer

How It Works

Three simple steps to start receiving live event payloads from ConnectHub.

1 Create Endpoint

Generate a webhook endpoint in your developer dashboard or via the `/v1/webhooks` API. Provide a secure HTTPS URL that can accept POST requests.

2 Select Events

Subscribe to specific event types like `post.created`, `comment.added`, or `payment.received`. Only triggered events will be sent to your endpoint.

3 Verify & Process

Validate the HMAC signature in the `x-connecthub-signature` header. Respond with `200 OK` to acknowledge receipt and trigger our retry policy if needed.

Available Events

Filter and subscribe to the exact events your application needs. New events are added quarterly.

Event Name	Description	Trigger
post.created	A new post is published by a user or creator.	Immediate
comment.added	A new comment or reply is posted on content.	Immediate
user.followed	A user follows your tracked account or community.	Immediate
live.started	A live stream session begins broadcasting.	Immediate
payment.received	A fan subscription, tip, or purchase is completed.	Post-settlement
moderation.flagged	Content is flagged by AI or user report for review.	Immediate

Security & Verification

Every webhook payload is signed with your webhook secret. Always verify signatures before processing.

🔐

Signature Verification Required

ConnectHub signs payloads using HMAC-SHA256. Include the `x-connecthub-signature` header validation in your endpoint. Reject unsigned or mismatched requests.

const crypto = require('crypto');
const crypto = require('crypto');
const webhookSecret = process.env.CONNECTHUB_WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
  const sig = req.headers['x-connecthub-signature'];
  const payload = JSON.stringify(req.body);
  
  const expectedSig = crypto.createHmac('sha256', webhookSecret)
    .update(payload).digest('hex');

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

import hmac
import hashlib
import json

WEBHOOK_SECRET = os.environ['CONNECTHUB_WEBHOOK_SECRET']

def verify_payload(body, signature):
    expected = hmac.new(WEBHOOK_SECRET.encode(), 
                       body.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.route('/webhook', methods=['POST'])
def webhook():
    if not verify_payload(request.data, request.headers.get('x-connecthub-signature')):
        return 'Bad signature', 401
    return 'OK', 200
                    

# Example: Testing signature verification locally
curl -X POST https://your-api.com/webhook \
  -H "Content-Type: application/json" \
  -H "x-connecthub-signature: sha256=a1b2c3d4e5f6..." \
  -d '{"event":"post.created","data":{"id":"p_8832","author":"u_9921"}}'
                    

Payload Structure

All webhooks follow a consistent JSON envelope. Events include timestamps, retry metadata, and actionable data.

sample_payload.json

{
  "id": "evt_7x9a2b4c",
  "type": "post.created",
  "timestamp": "2025-03-12T14:32:00Z",
  "api_version": "v1",
  "data": {
    "object": "post",
    "id": "p_883291",
    "author_id": "u_992104",
    "content_type": "image_carousel",
    "visibility": "public"
  },
  "retry_count": 0
}

Retry Policy & Best Practices

🔄 Exponential Backoff

If your endpoint returns a `4xx` or `5xx` status, ConnectHub retries with backoff: 1m, 5m, 15m, 1h, 4h, 24h. After 5 failed attempts, the webhook is paused.

⚡ Idempotency

Webhook events may be delivered multiple times. Always use the `event.id` field to deduplicate and avoid processing the same action twice.

📝 Response Expectations

Respond within 3 seconds with `200 OK`. For heavy processing, acknowledge receipt immediately and queue the payload for async handling.