Skip to content

Webhooks

Send survey response data to 3rd party softwares.

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

{
"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
}
{
"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

FieldDescription
survey_idThe unique identifier of the survey.
survey_nameThe name of the survey.
platformThe platform from which the survey was accessed.
answer_group_idThe unique identifier of the answer group. If a survey has 5 questions, all responses can be grouped using answer_group_id.
respondent_idThe unique identifier of the respondent.
countryThe country code of the respondent.
qnaThe question and answer data.
answered_atThe timestamp when the respondent answered the first question.
webhook_idThe unique identifier of the webhook.
webhook_nameThe name of the webhook.
eventThe type of event.
timestampThe 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.

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)

Prevent replay attacks

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.