External Events

Events that occur in an external product or a third-party service are termed as external events. You can enable external events to trigger apps. To do this:

  1. Generate a target URL - link to where the app receives webhook data.
  2. Create a webhook in the external product or service, to subscribe to external events. When creating a webhook specify the target URL for the webhook to send data.
  3. Configure event listeners in the server.js file.

When an external event occurs, the webhook uses the target URL, notifies the app about the external event, and sends data to the app. The configured event listener invokes a callback method. The app logic in the callback method runs with the help of the event-specific payload passed to the callback method.

For a demonstration of how external events work, see the JIRA events Freshdesk sample app.

Notes:
  • The rate limit for external events is 250 triggers per minute.
  • The app execution timeout is 20 seconds.
  • The serverless environment supports webhook data (incoming content) whose content type is JSON or XML.
onAppInstall - Webhook Registration

To generate a webhook URL when an app is installed and use the URL to register the webhook:

  1. From the app’s root directory, navigate to the server.js file.
  2. In the callback method associated with the onAppInstall event,
    • Include the generateTargetUrl() method. The webhook URL generated is unique for each app installation.
    • Include an API request to the external product, for webhook registration. In the API request, ensure to specify the authorization mechanism (Basic) and the JSON object that the external product requires to successfully register the webhook.
    • Note: You can register multiple webhooks in this callback method.

  3. When a webhook is successfully registered, the external product sends a webhook id. This webhook id can be used to deregister the webhook, when the app is uninstalled. In the callback method, include a mechanism to store the webhook id.
Sample server.js file Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
exports = { events: [{ event: "onAppInstall", callback: "onAppInstallHandler" }], onAppInstallHandler: function(payload) { generateTargetUrl() .then(function(url) { //API call to the external product to register the webhook. }) .fail(function(err) { // Handle error }); } }
EXPAND ↓

onExternalEvent - Configure Event

To register an external event and the corresponding callback:

  1. From your app’s root directory, navigate to the server.js file.
  2. In the exports block, enter the event (onExternalEvent), corresponding callback, and callback function definition as follows:
    Note: Ensure to enter only one callback method for an event.
    Copied Copy
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    exports = { events: [ //This is the list of all events and the corresponding callback methods necessary for the external event. { event: "onAppInstall", callback: "onAppInstallHandler" }, { event: "onExternalEvent", callback:"onExternalEventHandler"} ], onAppInstallHandler: function(payload) { generateTargetUrl() .then(function(url) { //API call to the external product to register the webhook. }) .fail(function(err) { // Handle error }); }, onExternalEventHandler: function(payload) { //This is the callback function definition. //Include the logic to perform any action in Freshcaller. console.log("Logging arguments from the event:" + JSON.stringify(payload)); } }
    EXPAND ↓

Payload Attributes

When an external event occurs, the external product passes an event-specific payload as webhook data to the target URL (app framework). This data is passed as payload to the external event’s callback method.

Payload structure Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "account_id" : "value", "domain" : "value", "event" : "value", "region" : "value", "timestamp" : "value", "data" : { //Contains the list of objects related to the event. }, "headers" : {}, "iparams" : { "Param1" : "value", "Param2" : "value" } }
EXPAND ↓

The payload is a JSON object with the following attributes.

Attribute Type Description
account_id string Identifier of the Freshcaller account, auto-generated when the account is configured for a business.
domain string Domain name for the Freshcaller account. For example, acn.freshcaller.com.
event string Identifier of the event - onExternalEvent.
region string Region where the Freshcaller account is deployed.
Possible values: US, EU, EUC, AUS, and IND.
timestamp number Timestamp of when the external event occurs, specified in the epoch format.
iparams object Installation parameters specified as a JSON object of <parameter name>: <parameter value> pairs.
headers object Headers associated with the webhook data, specified as a JSON object of <header parameter name>:<header parameter value> pairs.
data object Event-specific webhook data, specified as a JSON object of key:value pairs.

Sample payload Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{ "account_id": "12345", "event": "onExternalEvent", "timestamp": 1583839686, "region": "US", "domain": "sample.freshcaller.com", "data": { "call": { "id": 123456, "phone_number": "+1234567891" } }, "headers": { "Content-Type": "application/json" }, "iparams": {} }
EXPAND ↓
onAppUninstall - Webhook Deregistration

To automatically deregister a webhook, when an app is uninstalled:

  1. From the app’s root directory, navigate to the server.js file.
  2. In the callback method associated with the onAppUninstall event,
    • Include the mechanism to retrieve the webhook id saved during app installation.
    • Include an API request to the external product, for webhook deregistration.
Sample server.js file Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
exports = { events: [ //This is the list of all events and the corresponding callback methods necessary for the external event. { event: "onAppInstall", callback: "onAppInstallHandler" }, { event: "onExternalEvent", callback:"onExternalEventHandler"}, { event: "onAppUninstall", callback:"onAppUninstallHandler"} ], onAppInstallHandler: function(payload) { generateTargetUrl() .then(function(url) { //API call to the external product to register the webhook. }) .fail(function(err) { // Handle error }); }, onExternalEventHandler: function(payload) { //This is the callback function definition. //Include the logic to perform any action in Freshcaller. console.log("Logging arguments from the event:" + JSON.stringify(payload)); }, onAppUninstallHandler: function(payload) { //Include API call to the external product to deregister the webhook } }
EXPAND ↓

For a demonstration of webhook registration, webhook data storage and retrieval, and webhook deregistration, see the Freshdesk gitHub Issues sample app.

Test

For information on how to test external events, see Test the App.

Test with ngrok
Note: To test a serverless app, use the latest version of Chrome.

The FDK uses the node module ngrok to create secure tunnels between a local FDK instance and the ngrok cloud. According to ngrok.io, ngrok exposes local servers behind NATs and firewalls to the Internet, over secure tunnels. The FDK leverages this feature to expose the webhook registered in external products, to test external events app integrations.

To test external events by using ngrok:

  1. From the command line, navigate to the directory that contains the app related files and run the following command: $ fdk run --tunnel
  2. If you have ngrok authorization privileges, run the following command: $ fdk run --tunnel --tunnel-auth The tunnel is opened and an appropriate message specifying the URL to test serverless events is displayed.
  3. In the address bar of the browser, enter https://localhost:10001/web/test. A dialog box is displayed.
  4. Click Select an event. The events configured in the server.js file are displayed (onAppInstall, onAppUninstall, and onExternalEvent).
  5. Click onAppInstall. The webhook is registered in the external product.
  6. Navigate to the external product and simulate the event to which the webhook has subscribed. The event specific webhook data is sent to the app.