External Events

Apps can be invoked in response to events that occur in an external product or service by creating webhooks in that product or service. Webhooks enable you to subscribe to certain events. Every time the event occurs, the webhook is triggered and notifies the App Framework which in turn invokes the relevant app.

Sample Use Cases

  • Proactive Support: You want to create a ticket in Freshdesk when a certain event occurs (e.g. a payment in Stripe fails).
  • Data Sync: You want to make the same change in the corresponding Freshdesk contact when a contact is created or modified in an external product.
  • Real-time Updates: You want to notify the agent to whom a ticket is assigned when a JIRA issue that has been linked to a Freshdesk ticket is closed. You can even send a reply to the ticket requester.

Note:
1. You need to have CLI v4.0.0 or higher in order to use this feature. For more information on how to get the latest version, click here.
2. The rate limit for receiving external events is 250 per minute.
3. The timeout period for the app execution is 20 seconds.

Take a look at JIRA events app for a demonstration of this feature.

Payload

When an external event occurs, the corresponding method in the server.js file is invoked and the following payload is passed to the app.

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
{ "account_id" : "value", "event" : "value", "region" : "value", "timestamp" : "value", "domain" : "value", "headers" : {}, "data" : {}, "iparams" : { "Param1" : "value", "Param2" : "value" } }
EXPAND ↓

Attribute Type Description
account_id number Freshdesk account ID
event string Name of the event (onExternalEvent)
region string Region where the app is installed, either "US", "EU", "EUC", or "AUS"
timestamp number Time (epoch format) the event was received
domain string Freshdesk account domain
headers object Webhook headers
data object Webhook payload, the size should not exceed 128 KB
iparams object Installation Parameters

Sample payload from JIRA

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{ "account_id": 12345, "event": "onExternalEvent", "timestamp" : 1496400354326, "region" : "US", "domain": "https://xyz.freshdesk.com", "data": { "id": 2, "timestamp": "2009-09-09T00:08:36.796-0500", "issue": { "expand":"renderedFields,names,schema,transitions,operations,editmeta,changelog", "id":"99291", "self":"https://jira.atlassian.com/rest/api/2/issue/99291", "key":"JRA-20002", "fields":{ "summary":"I feel the need for speed", "created":"2009-12-16T23:46:10.612-0600", "description":"Make the issue nav load 10x faster", "labels":["UI", "dialogue", "move"], "priority": "Minor" } }, "changelog": { "items": [ { "toString": "A new summary.", "to": null, "fromString": "What is going on here?????", "from": null, "fieldtype": "jira", "field": "summary" } ], "webhookEvent": "jira:issue_updated" } }, "headers": { "Content-Type": "application/json" }, "iparams": { } }
EXPAND ↓
onExternalEvent Registration
To register an external event with the corresponding callback to perform an action, use the following format.

server.js Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
exports = { events: [ { event: "onExternalEvent", callback: "onExternalEventHandler" } ], onExternalEventHandler: function(payload) { console.log("Logging arguments from onExternalEvent: " + JSON.stringify(payload)); if(payload.data.thirdpartyissue.id = 3) { //your code to perform action within freshdesk } } };
EXPAND ↓

Note:
1. Include the event and callback definition in the exports block.
2. Include only one callback function for an event.

Webhook Registration

This is a one-time process which is generally performed during app installation. In order to register a webhook, you need to:

  1. Generate the webhook URL using the generateTargetUrl() method. This URL is unique for each app installation and is invoked when the event occurs.
  2. Make an API call to register the webhook with the third-party service or product. At present, only basic authentication is supported for webhook registration.
  3. Store the ID of the created webhook. This will enable you to delete the webhook when it is no longer needed.

server.js Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
exports = { events: [ { event: "onAppInstall", callback: "onAppInstallHandler" } ], onAppInstallHandler: function(payload) { generateTargetUrl() .then(function(url) { //Include API call to the third party to register your webhook }) .fail(function(err) { // Handle error }) } };
EXPAND ↓

Note:
1. The generateTargetUrl() method is supported only in onAppInstall() and product event callbacks.
2. The app can register multiple webhooks in the app install callback.

Webhook Deregistration

You need to deregister the event’s webhooks when your app is uninstalled.

server.js Copied Copy
1
2
3
4
5
6
7
8
exports = { events: [ { event: "onAppUnInstall", callback: "onAppUninstallHandler" } ], onAppUninstallHandler: function(payload) { //Include API call to the third party to deregister your webhook } };
Testing

You can easily test your app in your machine by simulating events. Also, you can test different scenarios by directly modifying the payload.

Note:
As the testing is only a simulation of events, an actual event will not be recorded in the back end. If you need an actual ticket/contact to be created, then it is recommended that you publish your app as a custom app and test the operation manually.

To simulate events for local testing, follow the procedure outlined below.

  1. In your console, navigate to your project directory, and execute the following command. $ fdk run
  2. Open your browser and enter the following URL to start testing your app: http://localhost:10001/web/events.
  3. Select the event that you want to simulate.
  4. Once you select an event, the corresponding event payload is displayed. Edit the values and click Simulate. When you edit the payload, ensure that you adhere to the JSON format.
  5. If the event is successfully simulated, you will see Success displayed.
  6. If there is a problem, you will see Failed displayed. Check if the payload is valid and then resume testing.

Log in with your Freshdesk account

Enter your helpdesk URL to proceed to login

Proceed

By clicking "Proceed", you agree to our Terms of Use.