Webhooks

Webhooks allow you to receive notifications from Frigade when certain events occur. You can use webhooks to receive notifications about your users when they start a Flow and as they progress through it.

​

Creating a webhook

To add a new webhook, open the Webhooks page from the left sidebar in the Frigade dashboard and click the “Add webhook” button.

​

Supported events

The following events are currently supported:

• flowResponse.startedFlow - when a user starts a Flow
• flowResponse.completedFlow - when a user completes a Flow
• flowResponse.abortedFlow - when a user aborts a Flow
• flowResponse.startedStep - when a user aborts a Step in a Flow
• flowResponse.completedStep - when a user completes a Step in a Flow

​

Webhook payload

The payload of the message includes the type of the event in the type property.

The data property contains the actual payload sent by Frigade. The payload can be a different object depending on the event type. For example, for flowResponse.* events, the payload will always be a Flow Response object.

{
   "type": "flowResponse.completedStep",
   "signature": "cabff19d9da06705f62c26c2a66154",
   "time": "2020-01-01T00:00:00.000Z",
   "data": {
      // flowResponse object
  }
}

​

Verifying webhooks

When you create a webhook, Frigade will generate a secret key for you. You can use this key to verify that the webhook is coming from Frigade.

To verify the request, you need to calculate the HMAC SHA256 hex digest of the JSON-encoded data field using the secret key as the key and compare it to the value signature field. Note that when JSON-encoding the data field it needs to match the order of the keys in the payload and not contain any whitespace between the keys and values.

For example, in Node.js, you can do it like this:

const crypto = require('crypto');

const payload = {
  type: 'flowResponse.completedStep',
  signature: 'cabff19d9da06705f62c26c2a66154',
  time: '2020-01-01T00:00:00.000Z',
  data: {
    // flowResponse object
  },
};

function verifySignature(secret, payload) {
  return (
    crypto
      // sign the string with sha256 using your secret
      .createHmac('sha256', secret)
      // If payload is already decoded, you need to stringify it first
      .update(Buffer.from(JSON.stringify(payload.data), 'utf-8'))
      // base64 encode it
      .digest('base64')
  );
}

const signature = verifySignature('secret', payload);

if (signature !== payload.signature) {
  throw new Error('Invalid signature');
}

​

Verifying timestamps

The time field in the payload is the time when the event occurred. You can use this field to verify that the request is not a replay attack by ignoring older events.

​

Retrying failed requests

Frigade will retry failed requests up to 5 times with an exponential backoff strategy.