How do I use Webhooks in Droplet Forms?

What are Webhooks?

Webhooks are a way to connect Droplet submission data to external systems. When a submission reaches a workflow state with a webhook set up, Droplet will send the submission data to a destination specified in the webhook. This makes it easier for you to push data from Droplet submissions into the systems or integrations you care about. Webhooks push data, vs API use that pulls data.

Setting up Webhooks

Webhooks look like this in the workflow code editor:

{
  "review": {
    "webhooks": {
			"onEnter": [
	      { "url": "http://example.com/webhook-receiver1" },
				{ "url": "http://example.com/webhook-receiver2", "secretId": "1235" }
			],
			"onExit": [
	      { "url": "http://example.com/webhook-receiver3", "secretId": "1236" }
	    ]
	}
  }
}

Create a webhook by adding a new "webhooks" property to a workflow step.

You can add webhooks to the "onEnter" and/or "onExit" hook. Each hook accepts an array of webhook objects that have a required "url" field and an optional "secretId" field. When the submission enters or exits the step with a webhook configured, Droplet will send a POST request to each webhook URL in that hook with the submission data in the body.

The POST body will look like this:

{
	"submission": {
		"data": {}, // the submission data
		"submittedBy": { "name": "asdfas", email: "[email protected]" },
        "assignedTo": {}, // if assigned to someone, will contain the name and email
        "status": "completed", // workflow status - draft, rejected, etc
        "step": "completed", // name of the workflow step the submission is on
        "id": 1234 // submission ID
	}
}

Adding Authentication

The "secretId" on webhooks is for authenticating webhook requests. It is optional for testing but should be required for real-world production use. If you have an unsecured API that allows POST requests from the internet, someone will likely find it and use it to their advantage.

To avoid this, add authentication to your webhook endpoint and store the auth token as a secret in Droplet. Generate a random secret. Droplet will then use the stored secret when calling your webhook endpoint by sending the stored secret in the HTTP Authorization header as a Bearer token. The header will look like Authorization: Bearer [secret].

Adding a Secret to a Webhook

In the form builder, click the meatball menu (triple dots), and click the “Add A Secret” menu option. This will show a modal to enter a secret label and secret. Enter a secret and a label and hit “save”. The ID of the saved secret will be copied to your clipboard.

Then, go to the workflow code editor and add a "secretId" property to the webhooks object you want to authenticate. Paste the copied "secretId" there.

Once a secret is saved in Droplet, you can’t see the value again. Currently, there is no UI for updating secrets or listing their metadata.

Adding Authentication to a Webhook Endpoint

Since Droplet sends the secret in an HTTP header, you can add authentication to your webhook endpoint by checking for the value of the secret. Specifics for doing this will depend on what you’re using to host your webhook, but here is a tiny node.js HTTP server that demonstrates checking the Authorization header:

const http = require('http');

const server = http.createServer((req, res) => {
  const auth = req.headers['authorization'];

  if (auth === 'Bearer [secret]') {
		// we have an authenticated request! Save the data, go wild, etc.
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('Welcome, authenticated user!');
  } else {
		// unauthenticated request, turn them away with a stern look
    res.writeHead(401, { 'Content-Type': 'text/plain' });
    res.end('ಠ_ಠ NO');
  }
});

const PORT = 3000;
server.listen(PORT, () => console.log(`Server running on port ${PORT}`));

All setup for the webhook endpoint will need to be managed by your organization. If you need assistance setting up the webhook object within the Droplet Form, please reach out to our Support Team at [email protected].