Authenticate an Element Instance with Events (API)

This section provides a summary of how to authenticate an element instance with events. Each element is different, so take a look at the Events section of the Element Guide. You can authenticate via Cloud Elements 2.0 or APIs.

Authenticate an Element Instance with Polling

Authenticating an element instance with events works the same as authenticating an instance, you just need to turn on events and set a few more parameters.

To authenticate an element instance with polling events add the polling configuration to the JSON body of your POST /instances request. See the Authenticate and Events sections of the Element Guide for the element that you want to monitor for element-specific steps.

For more information about each field described here, see Polling Parameters.

Polling Configuration

In the configuration JSON object, add the following event and polling configuration parameters when authenticating an element instance with polling events:

• event.notification.enabled: true
• event.vendor.type: polling
• event.notification.callback.url: <YOUR_CALLBACK_URL>
• event.notification.signature.key: <OPTIONAL_SIGNATURE_KEY>
• event.poller.refresh_interval: <NUMBER IN MINUTES>
• event.poller.configuration: <POLLING_CONFIGURATION>

Here is an example of an element that uses Basic authentication with the required polling configuration values. The usual body to authenticate an element instance only includes the username and password parameters, the rest are event and polling-specific parameters.

{
  "element":{
    "key":"elementKey"
  },
  "configuration":{
    "username": "xxxxxxxxxxxxxxxxxx",
    "password": "xxxxxxxxxxxxxxxxxxxxxx",
    "event.notification.enabled": true,
    "event.vendor.type": "polling",
    "event.notification.callback.url": "http://mycoolapp.com",
    "event.poller.refresh_interval": "<minutes>",
    "event.notification.signature.key": "xxxxxxxxxxxxxxxxxxxxxxxxx",
    "event.poller.configuration":{
      "contacts":{
        "url":"/hubs/crm/contacts?where=lastUpdated>'${gmtDate:yyyy-MM-dd'T'HH:mm:ss'Z'}'",
        "idField":"id",
        "datesConfiguration":{
          "updatedDateField":"_info.lastUpdated",
          "updatedDateFormat":"yyyy-MM-dd'T'HH:mm:ss'Z'",
          "updatedDateTimezone":"GMT",
          "createdDateField":"_info.lastUpdated",
          "createdDateFormat":"yyyy-MM-dd'T'HH:mm:ss'Z'",
          "createdDateTimezone":"GMT"
        }
      }
    }
  },
  "tags":[
    "<Add_Your_Tag>"
  ],
  "name":"<INSTANCE_NAME>"
}

Polling Parameters

Labels and buttons on the UI correspond to parameters in the JSON. The table below shows UI labels and buttons in bold and the equivalent parameters in the configuration JSON object in code formatting.

Authenticate an Element Instance with Webhooks

Authenticating an element instance with events works the same as authenticating an instance, you just need to turn on events and set a few more parameters.

To authenticate an element instance with webhook events add the webhook configuration to the JSON body of your POST /instances request. See the Authentication and Events sections of the Element Guide for the element that you want to monitor for element-specific steps.

For more information about each field described here, see Webhooks Parameters.

Webhook Configuration

In the configuration JSON object, add the following event and webhook configuration parameters when authenticating an element instance with webhook events:

• event.notification.enabled: true
• event.vendor.type: webhooks
• event.notification.callback.url: <YOUR_CALLBACK_URL>
• event.notification.signature.key: <OPTIONAL_SIGNATURE_KEY>

Here is an example of an element that uses Basic authentication with the required polling configuration values. The usual body to authenticate an element instance only includes the username and password parameters, the rest are event and polling-specific parameters.

{
  "element":{
    "key":"elementKey"
  },
  "configuration":{
    "username": "xxxxxxxxxxxxxxxxxx",
    "password": "xxxxxxxxxxxxxxxxxxxxxx",
    "event.notification.enabled": true,
    "event.vendor.type": "webhooks",
    "event.notification.callback.url": "http://mycoolapp.com",
    "event.notification.signature.key": "xxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "tags":[
    "<Add_Your_Tag>"
  ],
  "name":"<INSTANCE_NAME>"
}

Webhook Parameters

Labels and buttons on the UI correspond to parameters in the JSON. The table below shows UI labels and buttons in bold and the equivalent parameters in the configuration JSON object in code formatting.