Product User Community

Event Callbacks

January 01, 2020
Deltek, Inc
Deltek

Overview

A callback is a request that's automatically sent from ConceptShare to your specified endpoint when particular ConceptShare events occur. They are an integral part of just about any integration, and serve the purpose of explicitly verifying and attesting to the occurrence of events within ConceptShare. Without callbacks, you cannot accurately perform common actions, such uploading assets programmatically (see Topic Guides: Asset Ingestion), or indeed any action which requires asynchronous processing within ConceptShare.

A callback contains general information as well as specific event information so you can have your systems react accordingly to create your desired workflow. Callbacks in ConceptShare allow for relatively quick integrations without having to do custom programming within the ConceptShare environment. At this time, callbacks are URL based and can either be a GET or POST request. Both types of requests support variable substitution, where event variables can be replaced if the appropriate tag is placed on the URL. POST requests have the added benefit in that all the event variables are included in the POST body as FORM elements so you can iterate through them as needed.

Which events can I configure callbacks for?

All ConceptShare events support callbacks; however, some events may only have basic information such as the event name, and identifier.

How do I know which variables are available for a particular event?

The API Reference Documents section has a page listing all the Callbacks and their respective parameters. Click the button below to see the full Callback Reference Documentation.

Callbacks


ConceptShare provides a page which will simply log the event data passed to it. By configuring a callback, pointing to this particular page and generating the desired event, you can see in the logs, what the response was and which variables are included.

To use this method of testing callbacks you can do the following:

  1. Create a callback for your desired event and point it to the URL shown below (where youraccount and yourdomain are your particular ConceptShare account and domain respectively)
  2. Generate the event and check either the logs or the callback status in the Administration Panel. When the callback is complete, depending on the endpoint you used, the items will either be logged or echoed back to the caller and you can check the history for the results.
Log Callback: http://www.youraccount.yourdomain.conceptshare.com/system.ashx?f=lp
Echo Callback: http://www.youraccount.yourdomain.conceptshare.com/system.ashx?f=ep



EVENT_GUID         => 123456ab-12ab-9876-1234-12345678abcd
EVENT_ID           => COMMENT_CREATED
COMMENT_ID         => 178
ASSET_ID           => 13
PROJECT_ID         => 6
DELIVERABLE_ID     => 
COMMENTOR_ID       => 3
COMMENTOR_NAME     => "Testy McTestface"
COMMENTOR_USERNAME => "testy.mctestface@fmail.com"
COMMENT	           => "Needs more cowbell"
DRAFT	           => False
An example of what the response body might look like for a COMMENT_CREATED event:

As you can see from the above response, this particular event contained 11 variables. You can now write the appropriate code to react to such events to generate your required workflow.

There are also 3rd party tools you can use in order to inspect and familiarize yourself with callbacks. For example, services such as Request Bin allow you to create a temporary test endpoint which you can point ConceptShare callbacks to, for the purpose of logging and inspecting their data and structure.

How do I create and configure a callback?

Manually Configuring Account Level Events

To manually configure an event callback for a specific account, Click the Settings (gear) icon, and select Account Callbacks.

ConceptShare Account Callbacks Dropdown

From there, you can click the + to create a new entry, or to edit existing callback event subscriptions.

ConceptShare Add Account Callback Dialog

Manually Configuring Instance-wide Callback Events

If you have your own dedicated instance, as a ConceptShare Instance Administrator, you also have access to create callbacks that can be triggered by any account on the instance. To start creating a callback, log into the Administration Panel for your installation which is located http://www.youraccount.yourdomain.conceptshare.com/AdminPanel

ConceptShare Admin Integrations Tab

Once logged in, click on the Integrations tab to display the list of currently configured callbacks. Click on “Add Callback” and this will display the dialog to create and edit callbacks.

ConceptShare Admin Add Callback Dialog

Listed below are the common callback parameters and their descriptions:

Field Description
URL The location where you want the callback to make the request too. This is a URL on a system in your environment where you want to listen for events. Furthermore you can choose your request method (GET or POST).
Authorization Header An optional string to add to all callbacks to populate in the Authorization Http Header.
Is Enabled There are times when you want to turn callbacks on and off depending on certain scenarios (i.e. development vs. production callbacks) and toggling this will determine if the callback is active or not.
Default: Enabled
Account ID If you want the callback to only listen on a particular account/domain, you can put the account id in this box. Otherwise, callbacks listen across all accounts.
Default: Blank
Retry This is an option to determine if for whatever reason the callback could not complete (i.e. network issue, connectively, server error, etc.) whether to retry sending the callback again.
Default: Enabled
Delay If callback retries are enabled, this will determine how long between retries to wait. This value is given in seconds
Default: 300 seconds
Max Retry Attempts The maximum number of attempts to retry a callback before giving up.
Default: 3
Event Filter This is the list of events to listen for. You can select multiple events for a given callback and a request will go out for each instance of the given event. There is an option for “All Events”, however, this should only be used with caution as many events are fired in ConceptShare and may overwhelm a server if a large number of requests are generated. You don't want to accidentally launch a DoS attack against your own endpoint.
Deltek, Inc
Deltek