Centercode Guides to Endpoint Specific Systems
      Back to home
      1. Help Center
      2. Enhanced Integrations & APIs
      3. Centercode Guides to Endpoint Specific Systems

      Referencing external tools via Webhooks - GET request example

      Look up users (or feedback) in government trade lists, Salesforce, external issue trackers, and more

      This article applies to Team and Legacy editions.

      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 .

      In this guide, we’ll be using a Webhook with External Data integration to run a cursory check on potential testers via https://api.trade.gov. Then, we’ll record the lookup results to take informed action.

      In this example, we’ll be sending users’ names to trade.gov to identify any matches, indicating potential involvement in export infractions by the Department of Commerce, State, and the Treasury. The principles included in this guide apply to triggering a Feedback or User Webhook Macro within Centercode to any API-capable endpoint. 

      In this guide, you will:

      1. Create an (or identify an existing) API Key in Centercode
      2. Register for an API Key at api.trade.gov
      3. Create a GET Webhook Request with External Data in Centercode

      In order to configure both sides of this integration, you will need:

      1. Access to an existing API Key or Community Manager access to create a new one
      2. Project Manager access in the project of your choice (or your project template)

      Preparing to send data to your external system

      1.   Creating an API Key

      From the Centercode side, the first step in any API integration is to ensure that you have an API Key available within your Centercode Community. While this integration doesn’t use an API key, your integration features won’t be visible unless one is available.

      If necessary, create a Community API Key by following steps outlined here.

      2.  Generate your third-party’s API Key

      You may need to utilize an API Key generated by the third party system that’s specific to your account. Some services may provide your specific API Key and authentication in their provided API Endpoint URL. In this example, trade.gov provides your account with a unique API key once you've registered. 

      To get started at api.trade.gov:

      1. Register for an account to receive an API Key
      2. Click Get an API Key in the left-hand menu

      3.  Creating a webhook macro

      Macros allow you to create a single instruction that includes a set of actions to complete a desired task.  In this example, we’re creating a User Macro with a Webhook to send names to trade.gov, then capturing the return values.

      From the Community or Project Homepage:

      1. Click Management > Users > Project users in the upper Navigation Bar
      2. Click User resources
      3. Click the Create a macro button
      4. Enable the Trigger webhooks option
      5. Click Web Request and select GET
      6. Enter api.trade.gov’s API Endpoint into the Web Request text field
        https://api.trade.gov/consolidated_screening_list/search?api_key= {your key}&q={term}
      7. Add the necessary authentication Headers (discussed below)
      8. Enable and configure the Capture Return Values options (discussed below)
      9. Click Show in User Management Actions
      10. Click Submit

      You’ve just created your Webhook Macro to check trade.gov for results!

      Headers for authentication

      Headers allow you to define additional static values sent with each request. Not all API calls require headers to be defined. A common use for headers is to provide authorization for your Webhook by adding your access key to your header and specifying how you want returned values to be formatted.

      Authorization Header example:
      Authorization: 2nt6cs2EuPbF4keBBV7brZlP

      Return value formatting example:
      Content-Type: application/json

      Capturing return values

      Note that you can find more information on the definitions of these fields and options in our Integration Terms and Troubleshooting documentation. For this integration, the italicized text is used.

      • Create a new Data group label or select a pre-existing group
        eg. Blocklist
      • Label the data fields you're expected to receive and store
        eg. Blocklisted
      • Use Parameter to identify the data received in the response from the lookup
        eg. total
      • For each incoming data point, set its correct Type to properly classify it
        eg. Integer
      • Mark the incoming data field as a Favorite to display it on the user’s Summary or feedback ticket

      Using your data to your external system

      Once your Webhook Macro is configured, you may use it to send user data to your external system to capture return data. In this example, we’ll send user’s names to trade.gov to capture any matches.

      4. Using your webhook

      Now that you’ve created your Webhook Macro, it’s time to decide how you’d like it applied to your Feedback tickets within Centercode. Like any Macro within Centercode, you can trigger your macro manually on individuals or in bulk, as a Notice, or automatically on a scheduled cadence (Click here). 

      Bulk Manual Trigger
      In addition to running your Macro on a single user account, you also have the option to apply your Macro on users who match Filter criteria as an Action. 

      To trigger manually, start at the Community or Project Homepage:

      1. Click Management > Users > Project users in the upper Navigation Bar
      2. Create a Filter to target specific segments of users if desired
      3. Under Action, select your new Webhook Macro
      4. Click Perform action

      You’ve just sent your data to your third-party system and captured return data!

      5. Reviewing your webhook results

      The External Data returned from your third-party system extends the reach of your Centercode Data engine. These results can be leveraged in Reporting, User or Feedback Management, and the user’s summary or feedback ticket.

      Creating an external data view

       

      Viewing external data in user management

       

      Viewing external data in a user summary

      Troubleshooting your webhook

      If you find that your Webhook failed or that data isn’t updated as expected, you’ll want to review the Webhook’s logs to troubleshoot any issues. 

      From User Management:

      1. Click User resources
      2. Hover over your Macro and click Macro webhook log
      3. Hover over a username and click Macro webhook log

      Notes

      • trade.gov's API documentation can be found here
      • Please note that when sending a Post request to your Centercode API endpoint, the JSON body must be JSON encoded.