Webhooks
A webhook allows you to be automatically notified when something happens in Front without having to constantly poll the API. For each event happening in Front, your webhook will receive a POST HTTP request with the event JSON representation in the request body.
Front offers two methods for configuring webhooks:
- By adding a webhook feature to an app (application webhooks)
- By setting up a webhook through rules (rule webhooks)
If you are building a partner integration available to all Front users, you should use application webhooks. The primary benefit of this method is that users of your integration will not have to configure the webhook themselves when they install your app. There is also less risk of disruption when using application webhooks, because rules can be accidentally deleted or re-arranged by other teammates. Application webhooks have access to events that occur in shared inboxes.
If you are not building a partner integration, you can choose whether to use application webhooks or rule webhooks. Front recommends using application webhooks whenever possible, but setting up rule webhooks can sometimes be all you need. Application webhooks require that you have a server ready to respond to the webhook event at the time of configuration. This is not required when you set up a webhook through rules, so you can get up and running without first setting up a server. In addition, rule webhooks have access to the scope in which the rule was created. If the rule was created in a private inbox, then the rule webhook will have access to events in that private inbox.
The following table summarizes the differences between application webhooks and rule webhooks:
Webhook type | Recommended for partner integrations | Recommended for intial testing | Benefits | Scope |
---|---|---|---|---|
Application webhooks | Yes | Once you have a server set up to respond to webhook events | Does not require the end user to configure the webhook through a rule when installing your app Sends the full event payload | Shared inboxes |
Rule webhooks | No | Yes | Allows you to set up a webhook without having a server ready to respond during configuration, but would require users to configure the rule themselves if your app is ported to other Front instances Sends an event preview. You can make a subsequent API call to retrieve the full event. | Private or shared inboxes (the scope applies to the specific inbox the rule is created in) |
What events are not included in webhooks?
Webhooks alert you about most important events in Front. However, there are some events that webhooks do not apply to.
Webhooks exclude “mass action” events, such as:
- Moving inbox content to another team
- Mass updating inbox conversation statuses
- Importing historical messages to a channel
- Etc.
Configure Application Webhooks
Setup
Application webhooks are configured as features on the apps you create on the Developers page in Front. Refer to the Create, manage, and publish apps topic to learn how to create application webhooks.
Application webhook validation
In order to configure application webhooks in the Developer Settings as described in the Setup section, you need to have a server running which is able to respond to requests. When you attempt to save your webhook configuration (both on initial creation and on future updates), we will send the following notification to your webhook URL.
Header:
{
'x-front-signature': <built from your application signing key>,
'x-front-request-timestamp': <timestamp in milliseconds>,
`x-front-challenge`: <random string>
}
Body:
{
type: 'sync',
authorization: {
id: "cmp_abc" // company id you would see from /me
}
}
Verifying integrity
These steps will allow you to verify that the incoming application webhook originated from Front:
- Concatenate the stringified timestamp from the
x-front-request-timestamp
header with a colon - Convert the string from step 1 to a buffer
- Take the buffer from step 2 and concat it with the raw request body
- IMPORTANT: always operate on the raw request body to ensure signature stability
- Convert the concatenated buffer from step 3 to a string.
- Apply the
hmac
SHA256 algorithm using thetoken
provided during webhook configuration as the key [output in base 64]. - Compare the result from step 5 to the string provided in the
x-front-signature
header.
Example Javascript implementation:
const baseString = Buffer.concat([Buffer.from(`${timestamp}:`, 'utf8'), buf]).toString();
const hmac = crypto.createHmac('sha256', token)
.update(baseString)
.digest('base64');
const fromFront = (hmac === signature);
Responding to the validation request
To successfully validate the request, your application webhook must reply:
- Within 10s
- With a status code
200
- With one of the following content-type/body pairs:
content-type=text/plain
with the body being the value ofx-front-challenge
content-type=application/x-www-form-urlencoded
with a challenge parameter:challenge=<x-front-challenge-value>
content-type=application/json
with the body:{"challenge": "<x-front-challenge-value>"}
If the response doesn’t meet the criteria above, the validation is considered failed. You cannot save your change to your webhookUrl
if the validation fails.
Configure rule webhooks
Setup
For more information about how to enable and setup a rule webhook, please refer to our help center.
To quickly get started testing rule webhooks, you can use something like RequestBin or UltraHook to receive and explore webhook payloads.
Validating Data Integrity
For security reasons and since the rule webhook URL is open to the public, you should not trust any incoming requests that it receives. Each request we send to your rule webhook URLs will contain an X-Front-Signature header generated using the request body and your API Secret.
To validate that the data came from Front, you need to calculate the base64 encoded HMAC hash of the request body using the SHA1 algorithm and your API secret as the key. If the value matches the header's signature, you can be sure the request was sent from Front.
const crypto = require('crypto');
const apiSecret = 'YOUR_API_SECRET';
function validateFrontSignature(data, signature) {
var hash = crypto.createHmac('sha1', apiSecret)
.update(JSON.stringify(data))
.digest('base64');
return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(signature));
}
require 'openssl'
require 'Base64'
API_SECRET = 'YOUR_API_SECRET'
def validateFrontSignature(data, signature)
Base64.encode64(OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha1'), API_SECRET, data)).strip() == signature ? true : false
end
You can get your API secret by completing the following steps:
- Click Settings in Front.
- Under Company, click App store.
- Search for the Webhooks app.
- On the Webhooks app details page, click Configure app.
- Click Copy underneath the API secret section to obtain your API secret.
Timeouts
Webhook requests issued by Front will time out after 5 seconds.
Retries
Application Webhooks
Application webhooks will retry up to 3 times when Front receives an error or otherwise unrecognized response from your server. If you suspect you missed data by sending a bad response and also missing the retry opportunities, consider polling the List events API endpoint to filter for Events which occurred during the time you missed data.
Rule Webhooks
At present, retries are not attempted in cases where Front is unable to send payloads to your rule webhook. If you suspect you missed data, consider polling the List events API endpoint to filter for Events which occurred during the time you missed data.
Updated 8 months ago