Webhook Integration Guide

Webhooks allow you to receive real-time notifications when events occur in FeedbackEcho. This guide explains how to set up, secure, and handle webhook deliveries.

Overview

When you configure a webhook, FeedbackEcho sends HTTP POST requests to your specified URL whenever subscribed events occur. This enables you to:

  • Sync feedback data with external systems
  • Trigger automated workflows
  • Update dashboards in real-time
  • Send notifications to team channels

    • Setting Up Webhooks

    Creating a Webhook

  • Navigate to your organization settings
  • Go to Webhooks section
  • Click Create Webhook
  • Configure the webhook:
    • - Name: A descriptive name for identification - URL: Your endpoint that will receive events - Events: Select which events to subscribe to - Boards (optional): Filter events to specific boards

    Webhook Secret

    When you create a webhook, a secret key is generated. This secret is used to verify that webhook deliveries are genuine. Copy and store the secret immediately - it won't be shown again.

    Event Types

    Feedback Events

    After 5 failed attempts, the webhook will be marked as failed.

    Implement Idempotency

    Use the X-FeedbackEcho-Delivery header to handle duplicate deliveries:

    const processedDeliveries = new Set();
    app.post('/webhooks/feedbackecho', (req, res) => {
  const deliveryId = req.headers['x-feedbackecho-delivery'];
      if (processedDeliveries.has(deliveryId)) {
    return res.status(200).send('Already processed');
  }
      // Process the webhook...
      processedDeliveries.add(deliveryId);
  res.status(200).send('OK');
});

    Validate Timestamps

    Reject webhooks with old timestamps to prevent replay attacks:

    const MAX_AGE_SECONDS = 300; // 5 minutes
    function isTimestampValid(timestamp) {
  const now = Math.floor(Date.now() / 1000);
  return Math.abs(now - parseInt(timestamp)) < MAX_AGE_SECONDS;
}

    Testing Webhooks

    Test Delivery

    Use the "Send Test" button in the webhook settings to send a test payload:

    {
  "event": "test",
  "webhook_id": "whk_abc123xyz",
  "organization_id": "org_01HQXYZ",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "message": "This is a test webhook delivery from FeedbackEcho."
  }
}

    Local Development

    For local development, use a tunnel service like ngrok:

    ngrok http 3000

    Then use the ngrok URL as your webhook endpoint.

    Troubleshooting

    Webhook Not Receiving Events

  • Check webhook is enabled (green status)
  • Verify the correct events are selected
  • Check board filters aren't excluding events
  • Review recent delivery history for errors

    • Signature Verification Failing

  • Ensure you're using the raw request body (not parsed JSON)
  • Check the timestamp format is correct
  • Verify the secret hasn't been regenerated

    • Webhook Auto-Disabled

    Webhooks are automatically disabled after 10 consecutive failures. To re-enable:

  • Fix the underlying issue
  • Click Enable on the webhook
  • Use Send Test to verify it works

    • Support

    Need help? Contact us:

  • Email: support@feedbackecho.com
  • Documentation: https://docs.feedbackecho.com

Webhook Integration Guide - WCAG Pulse