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:

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:

1. Concatenate the stringified timestamp from the x-front-request-timestamp header with a colon
2. Convert the string from step 1 to a buffer
3. Take the buffer from step 2 and concat it with the raw request body
   1. IMPORTANT: always operate on the raw request body to ensure signature stability
4. Convert the concatenated buffer from step 3 to a string.
5. Apply the hmac SHA256 algorithm using the token provided during webhook configuration as the key [output in base 64].
6. 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:
  1. content-type=text/plain with the body being the value of x-front-challenge
  2. content-type=application/x-www-form-urlencoded with a challenge parameter: challenge=<x-front-challenge-value>
  3. 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:

1. Click Settings in Front.
2. Under Company, click App store.
3. Search for the Webhooks app.
4. On the Webhooks app details page, click Configure app.
5. 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.