Webhooks - Simple vs Secure REST Hooks with Formeezy

How do I receive webhooks for form submissions?

Webhooks are an easy way to get notified every time you receive a new form submission without having to poll or check for updates. Formeezy allows you to choose between simple and RESTful secure webhooks with main difference being that secure webhooks allow you verify the incoming webhook securely while ignoring potentially unwanted webhooks from another source.

Webhooks can be sent to a server, a serverless provider like Next.JS or AWS Lambda or Google Cloud Functions, or any other hosted cloud function provider. The examples below will cover a serverless example, but the code can be transferred into the use case of your choice.

Webhook Payload Example (JSON)

Copy
{
  email:"test@example.com",
  message:"Hi there! Testing out webhooks!",
  form_name:"Contact Page Form",
  referer:"http://example.com/app/forms/FORM_ID"
}

Adding Webhooks to a form

Add a webhook to any form in just a few clicks. To get started, visit the settings page of the form you would like to configure.

1. Open your form in Formeezy (https://formeezy.com/app/forms)
2. Click on your form to view its settings
3. Click "Integrations"
4. Click Webhooks

From here, you'll be asked to enter the URL endpoint that you would like to receive notifications at, as well as if you'd prefer to use our secure RESTful webhooks option. If you choose secure webhooks, you'll be prompted to generate a Webhook Secret that will be used in all notifications sent to this url.

Basic Webhooks Example

A basic webhook does not require a Webhook Secret of any kind, and will simply deliver the webhook payload in JSON format to the URL of your choice. This method is great for testing, but does expose your webhook endpoint to anyone who tries to submit a POST request.

We recommend using secure RESTful Webhooks for any production project.

Copy
export default async function (req, res) {
  // *** Do something with the request - Done! ***
  console.warn('We got a simple webhook!', req.body);

  return res.end();
}

Secure RESTful (REST Hooks) Webhooks Example

A secure webhook will allow you to verify an incoming webhook though the use of x-webhook-secret and x-webhook-signature in the headers of each request. Click here to learn more about REST Hooks on the official website by Zapier.

How do secure webhooks work?

You can verify the integrity of an incoming webhook with a simple handshake.

• When secure webhooks are enabled, we send a POST request to your webhook endpoint that includes a value in the headers for x-webhook-secret. This request does not include any payload, as it is just waiting for a confirmation response.

• From here, you can use your Formeezy Webhook Secret to decrypt the value and confirm that the values match. If they do not, the webhook should be disregarded. If the secrets do match, you simply respond with a mirror of the secret in your headers.

• When our server receives this, it will then POST the payload to your webhook endpoint along with x-webhook-signature in the headers. From there, you can verify once more that the secrets match and if they do, perform actions with the incoming webhook payload.

Formeezy uses the popular bcrypt encryption library which is supported by both PHP and Node JS.

Copy
import bcrypt from 'bcrypt';

export default async function (req, res) {
  const WEBHOOK_SECRET = process.env.FORMEEZY_WEBHOOK_SECRET;

  let hook_secret = req.headers['x-hook-secret'];
  let hook_signature = req.headers['x-hook-signature'];

  // *** STEP 1: Check the webhook secret ***
  // Validate the secret and mirror it in a response to our server.
  if (hook_secret) {
    let isValid = await bcrypt.compare(WEBHOOK_SECRET, hook_secret);

    if (isValid === true) {
      res.setHeader('x-hook-secret', hook_secret);

      return res.end();
    }
  }

  // *** STEP 2: Check the webhook signature ***
  // Validate the signature against your webhook secret.
  if (hook_signature) {
    let isValid = await bcrypt.compare(WEBHOOK_SECRET, hook_signature);

    if (isValid === true) {
      console.warn('We got an authenticated webhook!', req.body);

      // *** STEP 3: Do something with the validated request - Done! ***
      return res.end();
    }
  }

  // ERROR: The request was not successfully authenticated.
  return res
    .status(401)
    .json({ status: 401, message: 'Unauthorized Webhook Attempt' });
}

Managing Webhook Secret Keys

If you're using simple webhooks, you can disregard this section. If you're using secure webhooks, the guide below will walk you through managing your webhook secret and the changes that will occur when you make changes to it.

Create

• You can only have one Webhook Secret at a time.
• We recommend storing this value in your .env as you are only able to retrieve it once.
• If you lose your secret, you can refresh it, or delete it entirely.

Refresh

• If you need to rotate or your secret or gain access to the value, a refresh is the best method.
• Refreshing a secret is permanent and cannot be undone.
• When you refresh your webhook secret, we will generate a new secret that you have one-time access to.
• Any forms currently using secure webhooks, will automatically be updated on our end to utilize this new secret.
• Refreshing a secret will require you to update your .env file with the new value.

Delete

• Deleting a secret is permanent and cannot be undone.
• When you delete your webhook secret, any integrations currently relying on it will be deleted as well.
• Any simple webhook integrations will remain active.