Triggering Webhooks in AskNicely – AskNicely

Webhooks let you send real-time survey response data from AskNicely to any external system or application. When a contact responds to a survey, AskNicely can instantly push that data to a URL of your choice via an API call.

Getting Started

Webhook configuration is managed through the App Store.

Navigate to App Store in your AskNicely account.
Find and open the Webhooks app.
From here you can add a destination URL, configure custom headers, and manage your webhook settings.

When Is a Webhook Triggered?

A webhook fires in the following scenarios:

A contact submits a score - a webhook is sent as soon as a survey score is recorded.
A contact updates their response - if a contact changes their score or comment after submitting, a new webhook is triggered to reflect the update.

Configuring Headers

You can define custom HTTP headers to be included with every webhook request. This is useful for passing authentication tokens or other metadata required by your receiving system. Headers are configured directly within the Webhooks app in the App Store.

Webhook Payload

Each webhook delivers a JSON payload containing:

Contact details — including name, email, and any custom fields configured in your account.
Question details — including the score, comment, timestamps, delivery method, survey template, and any additional custom or AI-generated fields.
Note: The count property in the payload increments by 1 with each webhook fired for a given response. This lets you identify whether a payload represents an original submission or a subsequent update.

Example Payload

{
  "count": 1,
  "person": {
    "id": "163012",
    "name": "Firstname Lastname",
    "firstname": "Firstname",
    "lastname": "Lastname",
    "email": "tester@asknice.ly",
    "created": "1774990112",
    "segment": "general"
  },
  "question": {
    "id": "345094",
    "score": "10",
    "comment": "The gym was great, love it!",
    "sent": "1774990116",
    "opened": "1774990122",
    "responded": "1774990125",
    "segment": "general",
    "deliverymethod": "email",
    "survey_template": "Default",
    "review_site": null,
    "theme": null,
    "life_cycle": null,
    "ai_question_1": "The gym was great, love it!",
    "ai_question_2": "No",
    "ai_question_3": "abc",
    "brand_name": null,
    "city": null,
    "country": null,
    "gym": null,
    "gym_manager": null,
    "last_visit_at": null,
    "location_management_media_id": null,
    "location_name": null,
    "manager_name": null,
    "personal_trainer": null,
    "region": null,
    "scorecard1": "Great Knowledge & Advice",
    "scorecard2": null,
    "scorecard3": null,
    "state": null,
    "scorecard1_label": "Great Knowledge & Advice"
  }
}

Key Payload Fields

Field	Description
`count`	Number of times this webhook has fired for this response. Starts at 1, increments on each update.
`person.id`	AskNicely's internal ID for the contact.
`person.email`	The contact's email address.
`person.segment`	The segment the contact belongs to.
`question.score`	The score submitted by the contact.
`question.comment`	The comment left by the contact (if any).
`question.sent`	Unix timestamp of when the survey was sent.
`question.opened`	Unix timestamp of when the survey was opened.
`question.responded`	Unix timestamp of when the contact responded.
`question.deliverymethod`	How the survey was delivered (e.g. `email`).
`question.survey_template`	The name of the survey template used.
`question.ai_question_1/2/3`	Responses to AI-generated follow-up questions (if enabled).
`question.scorecard1/2/3`	Scorecard attribute values associated with the response.
Custom fields	Any additional fields (e.g. `gym`, `manager_name`, `region`) reflect the custom properties configured in your account. Fields with no value are returned as `null`.

Tips

Tracking updates: Use the count field to distinguish a first-time submission (count: 1) from an update (count: 2+).
Custom fields: The fields present in the question object will vary based on your account's configuration. Unused custom fields are included in the payload with a null value.

Related to