Skip to main content

Webhooks

Learn how to set up and use webhooks for real-time event notifications.

Overview​

Webhooks allow you to receive real-time notifications when events occur in Bellamy Book.

Note: The backend currently uses Kafka for event streaming and SignalR for real-time push (notifications, chat). A dedicated /api/webhooks endpoint may be added in a future release. The following is a conceptual guide for when webhooks are supported.

Supported Events​

  • post.created - New post created
  • post.updated - Post updated
  • post.deleted - Post deleted
  • comment.created - New comment added
  • reaction.added - Reaction added
  • user.registered - New user registered
  • friend.request.sent - Friend request sent
  • friend.request.accepted - Friend request accepted

Setting Up Webhooks​

Register Webhook​

POST /api/webhooks
{
  "url": "https://your-app.com/webhook",
  "events": ["post.created", "comment.created"],
  "secret": "your-webhook-secret"
}

Response​

{
  "success": true,
  "data": {
    "id": "webhook-id",
    "url": "https://your-app.com/webhook",
    "events": ["post.created", "comment.created"],
    "status": "active",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

Receiving Webhooks​

Webhook Payload​

Webhooks send POST requests with JSON payloads:

{
  "event": "post.created",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {
    "id": "post-id",
    "content": "Post content",
    "authorId": "user-id"
  },
  "signature": "webhook-signature"
}

Verify Signature​

Always verify webhook signatures:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(payload)).digest('hex');
  return digest === signature;
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET);
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook
  handleWebhook(req.body);
  res.status(200).send('OK');
});

Webhook Handler Example​

function handleWebhook(payload) {
  switch (payload.event) {
    case 'post.created':
      handlePostCreated(payload.data);
      break;
    case 'comment.created':
      handleCommentCreated(payload.data);
      break;
    // Handle other events
  }
}

function handlePostCreated(post) {

  // Your logic here
}

Managing Webhooks​

List Webhooks​

GET /api/webhooks

Update Webhook​

PUT /api/webhooks/{webhookId}
{
  "url": "https://new-url.com/webhook",
  "events": ["post.created", "post.updated"]
}

Delete Webhook​

DELETE /api/webhooks/{webhookId}

Testing Webhooks​

Test Webhook​

POST /api/webhooks/{webhookId}/test
{
  "event": "post.created"
}

This sends a test webhook to your endpoint.

Best Practices​

  1. Verify Signatures: Always verify webhook signatures
  2. Idempotency: Handle duplicate webhooks gracefully
  3. Retry Logic: Implement retry logic for failed deliveries
  4. Logging: Log all webhook events for debugging
  5. Security: Use HTTPS for webhook URLs

Next Steps​