Webhooks

Available on: Professional, Business plans

Formspree allows you to configure a webhook that will be triggered each time a form receives a new submission. Webhooks can be used with serverless functions, custom server code, or other 3rd party services, to perform custom handling of form submissions.

Serverless functions provide a light weight way to process form submissions. Rather than creating a full web server just to process form submissions, you can create a single serverless function and deploy it to a serverless platform. There are several platforms for hosting functions, such as AWS Lambdas and Google Cloud Functions. At Formspree we're also fans of runkit.io, a free service for running cloud functions, because it provides an easy way to edit, share and deploy simple function code. You can find our serverless code snippets at https://runkit.com/formspree.

When enabling your Webhook Plugin you'll be prompted to select a webhook , either "", or .

Simple Webhooks

These are normal webhooks. We'll just send the payload to the desired URL as POST requests without asking any questions.

Build Hooks

These are hooks that can be used to trigger new builds at third-party services like Netlify. This is basically a webhook with an empty body.

REST Hooks

In case you need it, we also send webhooks that adhere to the REST Hooks protocol. That is supported by some services and involves a handshake at the moment the webhook is being created.

Handling the Resthook handshake

When you choose the Resthook protocol, before Formspree begins sending webhook requests, it will send a confirmation request with an X-Hook-Secret header. See the resthooks docs on security for more information about the reshook handshake.

Here's an example of how to handle the reshook handshake using a RunKit.io function, however the same concepts apply if you're implementing in your own web server.

require("isomorphic-fetch")

exports.endpoint = function(req, res) {
    let url = req.url;
    
    if (url === '/hook') {
        
        let hook_secret = req.headers["x-hook-secret"]
        if (hook_secret) {
            
            // Step 1: Confirm the subscription this request 
            // includes an X-Hook-Secret

            res.setHeader("x-hook-secret", hook_secret)
            res.end();
        } else {
            
            // Step 2: Receive webhook requests!
            
            console.log("Received webhook! Now do something!")            
            res.end()
        }

    } else {
        res.end(url + "\n");
    }
}

In Step 1 above, the function responds to the initial resthook handshake with a response containing the correct headers. (see the above section on resthooks) The response is empty but mirrors back the x-hook-secret header from the request.

Next you must replace the code in Step 2 to perform your custom functionality. Runkit allows you to include common node libraries to help handle the request.

Webhooks Payload

A webhook is sent on every new submission received.

Except for Buildhooks (which are empty), the payload of the webhooks has the following structure:


{
  "form": "",
  "keys": ["keys", "in", "the", "order", "they", "were", "submitted"],
  "submission": {
    "_date": "2029-12-31T00:00:00",
    "field": "value",
    "other-fields": "other value",
    ...
  }
}

Plugins