Webhooks and Integrations

Add a Webhook

1. 1

   Open Integrations

   From the site menu, open Integrations (Pro or Max required).

2. 2

   Enter an HTTPS URL

   Paste your endpoint URL. Slack incoming webhooks, Zapier catch hooks, and custom receivers are supported. http://localhost and http://127.0.0.1 work for local tests.

3. 3

   Optional signing secret

   Add a secret to enable HMAC verification on incoming requests. FeedBlox sends X-Feedblox-Signature: sha256=... computed from the raw JSON body.

4. 4

   Send a test delivery

   Use Test on the webhook row to POST sample JSON and confirm your receiver returns 2xx.

Payload Shape

Each delivery uses event feedback.created with version 1. The feedback object includes id, site_id, sentiment, rating, comment, extra_response, automation_tags, and optional client_debug (same bundle as the inbox).

• Content-Type: application/json
• Idempotency-Key header set to the feedback id for safe retries
• X-Feedblox-Signature when a signing secret is configured
• User-Agent: FeedBlox-Webhooks/1.0

Verify Signatures

Compute HMAC-SHA256 of the raw request body with your webhook secret and compare to the X-Feedblox-Signature header (format sha256=<hex>). Reject requests that fail verification before parsing JSON.

REST API

Pro and Max accounts can create API keys under Dashboard → API Keys. Use Authorization: Bearer fbx_... against /api/v1 to list sites, manage webhooks, send test deliveries, and read feedback programmatically.

Slack and Linear

Many teams paste a Slack incoming webhook URL directly. For Linear or Jira, use Zapier or a small middleware service that maps the JSON payload into your ticket format. automation_tags and client_debug travel with the payload so routing rules can branch on tag or sentiment.

Examples

• Slack alert for every new report

  Scenario: You paste a Slack incoming webhook URL into Integrations for your production site.

  Outcome: When a visitor submits feedback, Slack receives a POST. Your channel shows the site name, sentiment, comment snippet, and a link back to the inbox row so the on-call engineer can open full client debug in FeedBlox.

• Sample JSON payload

  Scenario: A visitor submits negative feedback with the comment "Save button spins forever" and your automation tagged the row eng-triage.

  Outcome: Your endpoint receives a body like the example below. Use feedback.id as the Idempotency-Key if you retry processing.

  {
    "event": "feedback.created",
    "version": 1,
    "created_at": "2026-06-17T14:32:01.000Z",
    "feedback": {
      "id": "fbk_abc123",
      "site_id": "site_xyz789",
      "sentiment": "negative",
      "rating": null,
      "comment": "Save button spins forever",
      "extra_response": null,
      "automation_tags": ["eng-triage"],
      "client_debug": {
        "console": [
          { "t": 4200, "level": "error", "message": "Uncaught TypeError: Cannot read property 'id' of undefined" }
        ],
        "network": [
          { "t": 4100, "method": "POST", "url": "https://app.example.com/api/save", "status": 500, "durationMs": 842 }
        ],
        "jsErrors": [
          { "t": 4200, "message": "Cannot read property 'id' of undefined", "kind": "error" }
        ],
        "metadata": { "plan": "pro", "account_id": "acct_42" }
      }
    }
  }

• Route billing tags to a different channel

  Scenario: You run a small Node receiver instead of posting directly to Slack. Automations tag billing-urgent on negative checkout reports.

  Outcome: Your receiver reads automation_tags. If the array includes billing-urgent, post to #billing-alerts; otherwise post to #product-feedback. Same webhook URL, smarter routing.

• Verify the signature

  Scenario: You configured a signing secret on the webhook. A POST arrives at your endpoint.

  Outcome: Read the raw body as UTF-8, compute HMAC-SHA256 with your secret, prefix with sha256=, and compare to the X-Feedblox-Signature header. Reject mismatches before parsing JSON.

  // Node.js (conceptual)
  const crypto = require('node:crypto');
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
  if (req.headers['x-feedblox-signature'] !== expected) {
    return res.status(401).end('Invalid signature');
  }