External Events

Apps can be invoked in response to events that occur in an external product or service. This is done by creating webhooks in the external product. Webhooks are a mechanism that enables 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

  • Every time a certain event occurs (e.g a payment in Stripe fails), you want to proactively create a ticket in Freshdesk.
  • Every time a contact is created or modified in an external product, you want to make the same change in the corresponding Freshdesk contact.
  • When a JIRA issue that has been linked to a Freshdesk ticket is closed, you want to notify the agent to whom that ticket is assigned. You can even send a reply to the ticket requester.

Note:
1. You need to have SDK v3.1.0 or higher in order to use this feature. You can find instructions on how to get the latest version 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 the simple external events app for a demonstration of this feature.

Payload

When an external event occurs, the corresponding method in the server.js is invoked and the following payload is passed to the app to enable it to get the context about the event:

Copied Copy
1
2
3
4
5
6
7
8
9
10
11
12
{ "account_id" : "value", "event" : "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)
timestamp number Represents the time (epoch format) when the event was received.
domain string Freshdesk account domain
headers object Webhook headers
data object Webhook payload. The size should not exceed 128KB.
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
{ "account_id": 12345, "event": "onExternalEvent", "timestamp": 1500351361762, "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" } }
EXPAND ↓

onExternalEvent Registration
You will need to register the external event with the corresponding callback to perform an action as shown in the format below:

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. You should include the event and the callback definition within the exports block.
2. You should 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 lets the webhook know which endpoint it needs to hit when an event occurs and is unique for each installation of the app.
  2. Make an API call to register the webhook with the third party service or product. Currently, 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. Currently, we only support basic authentication for registering the webhook.
2. The generateTargetUrl() method is supported only in the onAppInstall() and in product event callbacks.
3. The app can register multiple webhooks in the onAppInstall callback.


Webhook Deregistration

You must deregister the event’s webhooks when your app is uninstalled as shown in the sample below:

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 } };

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.