Integrations & Webhooks

Webhooks let you receive real-time notifications whenever new feedback is submitted through your Voiseback widget. Instead of polling the dashboard for updates, your server or third-party services can be notified instantly, enabling automations like Slack alerts, CRM updates, email notifications, and more.

How Webhooks Work

When a visitor submits feedback through your widget, Voiseback processes the submission and then sends an HTTP POST request to your configured webhook URL. The request body contains a JSON payload with the feedback data, including the transcript, sentiment analysis, category, and metadata.

This happens at the end of the feedback processing pipeline — after audio upload, transcription, and AI analysis are complete — so the payload includes all available data.

Setting Up a Webhook

To configure a webhook for your project:

1. Navigate to Dashboard → Settings → Integrations.
2. Enable the Webhook toggle.
3. Enter your Webhook URL — this is the endpoint that will receive the POST requests. It must be a publicly accessible HTTPS URL.
4. Click Save.

Webhook Payload

Each webhook request is an HTTP POST with a Content-Type: application/json header. Here is the structure of the JSON payload:

{
  "event": "feedback.new",
  "feedback": {
    "id": "uuid",
    "transcript": "The onboarding flow is really smooth...",
    "sentiment": "positive",
    "category": "praise",
    "summary": "User praised the onboarding experience",
    "emotion": "satisfied",
    "intensity": "moderate",
    "is_testimonial_candidate": true,
    "page_url": "https://example.com/pricing",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Payload Fields

Event: feedback.wants_reply

When a visitor provides their email address and requests a reply, Voiseback sends a second webhook with the event type feedback.wants_reply. This event includes the visitor's email and the associated feedback data.

{
  "event": "feedback.wants_reply",
  "feedback": {
    "id": "uuid",
    "user_email": "visitor@example.com",
    "wants_reply": true,
    "transcript": "The onboarding flow is really smooth...",
    "sentiment": "positive",
    "category": "praise",
    "summary": "User praised the onboarding experience",
    "page_url": "https://example.com/pricing",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Use this event to trigger follow-up workflows — for example, creating a support ticket, sending an acknowledgment email, or alerting your team that a visitor is expecting a response.

Verifying Webhook Signatures

If a webhook secret is configured for your project, Voiseback includes a Webhook-Signature header containing an HMAC-SHA256 signature. You can verify this signature to confirm the request genuinely came from Voiseback and was not tampered with in transit.

The signature is computed by combining a timestamp with the raw request body and hashing the result with your webhook secret using HMAC-SHA256. The signature header follows the format t=<timestamp>,v1=<hmac>. Here is how to verify it:

Each webhook request also includes Webhook-Id (a unique delivery identifier) and Webhook-Timestamp headers for additional verification.

const crypto = require('crypto');

function verifyWebhook(body, signatureHeader, secret) {
  // Parse the signature header: "t=<timestamp>,v1=<hmac>"
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(p => p.split('='))
  );
  const timestamp = parts.t;
  const signature = parts.v1;

  // Recreate the signed payload
  const signedPayload = `${timestamp}.${body}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

In your webhook handler, use it like this:

app.post('/webhook/voiseback', (req, res) => {
  const signature = req.headers['webhook-signature'];
  const body = JSON.stringify(req.body);
  const secret = process.env.VOISEBACK_WEBHOOK_SECRET;

  if (!signature || !verifyWebhook(body, signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Signature verified — process the feedback
  const { event, feedback } = req.body;
  console.log('New feedback:', feedback.summary);

  res.status(200).json({ received: true });
});

Testing Webhooks

Before connecting webhooks to production systems, test your setup to make sure everything works:

1. Use a request inspector — services like webhook.site or RequestBin give you a temporary URL that logs incoming requests. Set this as your webhook URL to inspect the payload format.
2. Submit test feedback — go to your feedback page and submit a test response through the widget. The webhook should fire within a few seconds.
3. Check the payload — verify that the JSON structure matches what you expect and that all fields are present.
4. Verify the signature — confirm that your signature verification code accepts the request with the correct secret and rejects requests with an incorrect one.

Common Use Cases

Webhooks are flexible and can power a wide range of integrations:

Slack Notifications

Send new feedback to a Slack channel so your team sees it instantly. Use a middleware service or a simple server that receives the Voiseback webhook and forwards a formatted message to Slack's incoming webhook URL.

CRM Updates

Automatically log feedback in your CRM (HubSpot, Salesforce, etc.) by mapping the webhook payload fields to your CRM's contact or activity records.

Email Alerts

Trigger email notifications to your team when feedback matches certain criteria — for example, only send alerts for negative sentiment or bug reports.

Zapier and No-Code Tools

Use Zapier's webhook trigger (Catch Hook) to connect Voiseback feedback to thousands of apps without writing code. Map the payload fields to your Zap's actions for spreadsheet logging, task creation, and more.

Retry Behavior

Webhook requests have a timeout period. If your endpoint does not respond in time or returns a non-2xx HTTP status code, the delivery is considered failed. For critical integrations, we recommend building a resilient handler that processes data asynchronously and using a queue or middleware service that can handle retries on your end.

Troubleshooting

Webhook not firing

• Verify that the webhook URL is saved correctly in your project settings.
• Make sure the URL is publicly accessible (not localhost or behind a firewall).
• Check that feedback is actually being submitted — visit your replies dashboard to confirm.

Receiving a 401 or signature mismatch

• Confirm that the webhook secret in your project settings matches the secret in your verification code.
• Make sure you are verifying against the raw request body, not a re-serialized version (re-serializing can change field order or whitespace).
• Ensure you are reading the Webhook-Signature header correctly (header names are case-insensitive).

Payload fields are null

• The transcript, sentiment, category, and summary fields are null when AI processing was unavailable. Check your AI usage in Dashboard → Settings to see if you have reached the monthly cap.

Next Steps

For tips on writing effective prompts that generate high-quality feedback, see Creating Prompts.