Webhooks

Introduction

The webhook lets you receive real-time notifications about specific events, such as when a respondent completes a survey. By configuring webhooks, you can integrate FeedbackSpark with your applications and automate workflows based on these events.

Events overview

Currently, FeedbackSpark supports the following events:

1. Survey Completed: This event is triggered when a respondent completes a survey or closes a survey. So, if a respondent leaves the survey in between, it will not be triggered.
2. Survey Answered: This event is triggered when a respondent submits a survey response. So, if your survey has 5 questions, it will be triggered 5 times.

Example payload for each event

Event payload for Survey Completed

{
  "survey_id": 183,
  "survey_name": "My blank survey",
  "platform": "link",
  "answer_group_id": 24943,
  "respondent_id": "anon:7c079bf2-b1d0-4154-ac51-3a5e57e7df9e",
  "country": "IN",
  "qna": [
    {
      "order": 0,
      "question": "How satisfied are you with our service?",
      "answer": "5",
      "comments": null
    },
    {
      "order": 1,
      "question": "How likely is it that you would recommend SurveyHQ to a friend or colleague?",
      "answer": "10",
      "comments": null
    }
  ],
  "answered_at": 1719215254.837,
  "webhook_id": "2189da30-1d73-43e3-b63f-e6d9b972ac25",
  "webhook_name": "My First Webhook",
  "event": "survey_completed",
  "timestamp": 1719215273
}

Event payload for Survey Answered

{
  "survey_id": 183,
  "survey_name": "My blank survey",
  "platform": "link",
  "answer_group_id": 24943,
  "respondent_id": "anon:7c079bf2-b1d0-4154-ac51-3a5e57e7df9e",
  "country": "IN",
  "qna": {
    "order": 2,
    "question": "How satisfied are you with our service?",
    "answer": "5",
    "comments": null
  },
  "answered_at": 1719215254.837,
  "webhook_id": "7cf5a7cd-ee0e-42d6-bc0d-b03a256ea341",
  "webhook_name": "My second Webhook",
  "event": "survey_answered",
  "timestamp": 1719215272
}

Event object structure

Field	Description
survey_id	The unique identifier of the survey.
survey_name	The name of the survey.
platform	The platform from which the survey was accessed.
answer_group_id	The unique identifier of the answer group. If a survey has 5 questions, all responses can be grouped using answer_group_id.
respondent_id	The unique identifier of the respondent.
country	The country code of the respondent.
qna	The question and answer data.
answered_at	The timestamp when the respondent answered the first question.
webhook_id	The unique identifier of the webhook.
webhook_name	The name of the webhook.
event	The type of event.
timestamp	The timestamp when the event was sent.

Secure your webhook.

To secure your integration, check that the request is coming from FeedbackSpark and that the data has not been tampered with. You can use the following methods:

Verify the signature

All payloads sent to your webhook will include an X-Spark-Signature header. This header contains a signature generated using the HMAC algorithm with the SHA-256 hash function. The signature is generated using the webhook secret key and the event payload. You can verify the signature by generating a new one and comparing it with the signature in the X-Spark-Signature header.

Tip

You can find the your secret key in webhook integrations page.

Python

import hmac
import hashlib

def verify_signature(payload, signature, secret_key):
  calculated_signature = hmac.new(secret_key.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).hexdigest()
  return hmac.compare_digest(calculated_signature, signature)

Node.js

const crypto = require('crypto');
const secretKey = 'my-webhook-secret-key';

function verifySignature(payload, signature, secretKey) {
  const calculatedSignature = crypto.createHmac('sha256', secretKey).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(calculatedSignature, 'hex'), Buffer.from(signature, 'hex'));
}

Prevent replay attacks

Note

In a replay attack, an attacker intercepts a valid payload and its signature and then re-transmits them.

Each webhook includes an x-spark-timestamp header, which represents the time the webhook was sent. To guard against replay attacks, verify that this timestamp is within an acceptable time window (e.g., 5 minutes) of the current time.

Example code to verify the timestamp in Python:

import time

def verify_timestamp(timestamp, time_window_seconds):
    timestamp = float(request.headers.get('x-spark-timestamp', 0))
    current_time = time.time()
    event_time = float(timestamp)
    time_difference = abs(current_time - event_time)
    return time_difference <= time_window_seconds

# Usage
TIME_WINDOW = 300  # 5 minutes, adjust as needed
# In your webhook handler:
timestamp = request.headers.get('x-spark-timestamp')  # Adjust based on your framework
if not verify_timestamp(timestamp, TIME_WINDOW):
    return "Invalid timestamp", 400

Retry behavior

If a webhook fails to deliver an event, FeedbackSpark will retry sending the event up to 3 times at an equal interval of 10 minutes. If the event is still not delivered after 3 retries, the event will be discarded.

Duplicate events

Webhooks may be delivered more than once. Ensure that your system can handle duplicate events. Use the webhook_id to identify unique events.

Best practices

1. Use HTTPS: Always use HTTPS to secure your webhook endpoint.
2. Verify the signature: Verify the signature of the payload to ensure that the event is coming from FeedbackSpark.
3. Validate the timestamp: Validate the timestamp to prevent replay attacks.
4. Asynchronous processing: Process the webhook events asynchronously. A significant spike in events can overwhelm your system if processed synchronously.
5. Roll secret key: Rotate your secret keys periodically to enhance security. Click reconfigure in webhook integration page to generate a new secret key.