Centercode Guides to Simple API Integrations
      Back to home
      1. Help Center
      2. Enhanced Integrations & APIs
      3. Centercode Guides to Simple API Integrations

      Simple Guide to External Listeners

      This article applies to Team and Legacy editions.

      External Listeners allow external systems to trigger automation or store data within Centercode. Centercode “listens” at the External Listener’s URL for external systems to send data to that location (typically via webhook). 

      Note that while Centercode’s integration features are intended to be approachable by a Customer Validation Professional, you might need to enlist help from an internal technical resource and refer to our vocabulary and troubleshooting documentation.

      Common External Listener use cases include:

      • Updating Centercode statuses via your bug tracking system (Jira, Bugzilla, etc.)
      • Tracking and recording tester usage within your app - awarding points for certain features used
      • Automatically thanking a user for submitting a piece of feedback from within your app
      • Increase a user’s score based on live product usage

      Similar to other endpoints, your external system can store custom data or tell Centercode to take any action available through macros (sending emails, scoring users, updating statuses, deleting user accounts, or even triggering another integration).

      Prerequisite criteria 

      • Enhanced Integrations enabled 
      • Community-level API Key (click here)
      • Community or Project Manager access
      Image from Gyazo

      Creating your External Listener within Centercode

      External Listeners are located within User Automation or Feedback Automation and are conceptually similar to Centercode Macro Triggers. 

      From User or Feedback Automation:

      1. Click Create an external listener
      2. Enter an (internally-facing) Name and optional Description
      3. Add a Key identifier. This will show up in the Listener URL to help you identify this External Listener when it appears in your integrations
      4. (Optional) Add a Filter to narrow the available set of target users or feedback tickets
      5. Users or Feedback must match the filter for the listener to trigger

      At this point, technical help may be necessary - please work with a developer (and/or Centercode)

      1. Select your Listener Type - Macro Execution, Add Comment, or External Data (detailed below)
      2. Fill out the corresponding Listener Type fields
      3. Select your API Key
      4. Copy / Save the provided API Endpoint URL
      5. Save this URL - You’ll use the API Endpoint URL to direct requests from your external system
      6. Click Submit 

      You’ve just created your External Listener!

      External Listener Types

      External Listeners allow 3 different actions to occur against the user or feedback ticket within your Centercode platform when your Listener’s API Endpoint is triggered. 

      Macro Execution 

      Macro Execution allows you to trigger a Centercode Macro against users or feedback identified by your external system.

      Add Comment

      Add comment allows you to submit a comment on targeted user accounts or feedback tickets. 

      • Author Field refers to the parameter used in your external system to identify the author of the incoming comment. The author value must be the valid email address of a user account with access to post comments (typically an administrator account).  
      • Comment Field refers to the parameter used in your external system to identify the contents of the incoming comment. 

      Example of third-party key value pairs:

      External Data 

      External Data allows you to add data to Centercode from your third-party systems. Doing so stores this data against Users, Feedback Tickets, and Projects which can then be leveraged as Dynamic Tags in User and Feedback Management, Reporting, or even in other integrations.

      To configure an External Data Listener, select a pre-existing External Data Group or create a new one to identify and categorize data captured from your external system. These groups are functionally identical to User Account, Participation, or Surveys data groups.

      External Data Fields are shown in Reporting and User or Feedback Management as the Label and are mapped from your external system’s webhook request via the Parameter field.

      Selecting the correct data Type allows you to report on and visualize the stored data as the correct type

      • Boolean refers to values returned as true and false
      • Date and Time refers to dates and times returned
      • Integer refers to numbers to be returned
      • String refers to textual data returned

      Notes

      • Macro Execution Listeners can trigger any Centercode Macro, including those containing Webhooks. 
      • User-based Add Comment Listeners add Community- or Project-level User Comments, commonly capturing milestone events for tester accounts. In Feedback, Add Comment Listeners apply their comments to feedback tickets, potentially triggering Follow Notifications and influencing Popularity Scores.
      • For Add Comment Listeners, Author Field and Comment Field must exactly match the key or parameter in the JSON body of your third-party system. These are sometimes referred to as “key value pairs” where author_name is the “key” and the actual email address (e.g. jim@centercode.com ) is the “value”.
      • External Data Listeners follow the same “key value pair” design but let you pick the Label. The Parameter must still match the parameter sent by your third-party system.
      • Please note that when sending a Post request to your Centercode API endpoint, the JSON body must be JSON encoded.