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",
  "environment": "production",
  "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?",
      "question_type": "rating",
      "rating_range": 5,
      "rating_scale": "numerical",
      "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
      "question_type": "nps",
      "rating_range": 10,
      "rating_scale": "numerical",
    }
  ],
  "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?",
    "question_type": "rating",
    "rating_range": 5,
    "rating_scale": "numerical",
    "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	Unique identifier for the survey, auto-generated upon survey creation.
survey_name	Display name of the survey as defined by the creator.
platform	Distribution channel of the survey. Possible values: ‘email’, ‘web’, ‘link’, ‘mobile’.
environment	Indicates whether the webhook is from sandbox or production environment. Possible values: ‘production’, ‘sandbox’.
answer_group_id	Unique identifier that groups all responses from a single survey session. Used to correlate multi-question responses.
respondent_id	Unique identifier for the person answering the survey. Can be anonymous or linked to a user account.
country	Two-letter ISO country code (e.g.,‘IN’) identifying respondent’s country.
qna	JSON object containing question identifiers and their corresponding responses.
rating_range	The scale of the rating question. Possible values: 3 (1-3), 5 (1-5), or 10 (0-10/NPS rating).
rating_scale	Visual representation of the rating. Possible values: ‘numerical’, ‘emoji’, ‘star’.
answered_at	Unix timestamp (seconds since epoch) when the first question was answered (e.g., 1719215272).
webhook_id	Unique identifier for the webhook configuration that triggered this event.
webhook_name	Display name of the webhook as defined in the webhook configuration.
event	Type of webhook event that triggered this payload.
timestamp	Unix timestamp (seconds since epoch) when the webhook event was generated (e.g., 1719215272).

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-request-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-request-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-request-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.