Introduction
This guide walks you through a real-world example of using webhooks with your Fulcrum data. The process involves setting up a basic Node.js application to receive and process webhook events. For users with some programming experience, setup should be quick.
Prerequisites
This guide assumes you have:
Experience developing and deploying web applications.
A Fulcrum plan that supports webhooks.
The proper system role and permissions to manage webhooks (e.g., organization owner).
The Plan
This guide outlines the following steps to deploy and test a webhook endpoint:
Deploy a simple Node.js application to Heroku.
Create a webhook in Fulcrum that points to this application.
Create an app with data in Fulcrum.
Confirm that webhook event requests appear in Heroku logs.
Deploy a Node.js Application to Heroku
About Heroku
Heroku is a cloud platform that allows you to host and manage applications easily. You can deploy a small app for free, which is what we'll do here.
First, create a Heroku account and follow their Quick Start guide to:
Install the Heroku CLI (toolbelt).
Log in to your account using the CLI.
Deploy the Application
We'll use a simple example application called polis.js, which receives HTTP POST requests and writes their contents to STDOUT. This application will serve as our webhook endpoint.
In your terminal, follow these steps:
Navigate to a directory where you want to store the source code:
Bash
git clone https://github.com/fulcrumapp/polis.js.git cd polis.js
Create and deploy the application to Heroku:
Bash
heroku create git push heroku master
Note the output of this command, as it provides your webhook URL:
Bash
heroku domains
Test the Application
In your terminal, open your deployed site in the browser:
Bash
heroku open
You should see the confirmation message: “polis.js is running.”
Create a Webhook in Fulcrum to Use this application.
You will now link your Heroku application by configuring a new webhook within Fulcrum.
In your browser:
Log into your Fulcrum account.
Click your profile icon in the top-right corner.
If you belong to multiple organizations, select the correct one you want to use.
In the left-hand menu, click Webhooks.
Click + New Webhook.
Enter
polis.jsas the webhook name.In the URL field, enter your Heroku app's URL (from the
heroku domainscommand output).Click Save to create the webhook.
Create an App with Data in Fulcrum
Now that the webhook has been created, we can start using it.
Create a new app and a record within Fulcrum.
Since we have an active webhook within our organization, an event is created for both the app and the record you made.
Each event generates requests for each of the webhooks in your organization. With only one webhook configured, one request is made for the app and one for the record.
These requests are made to the webhook’s URL automatically, confirming that your Node.js application should have received the requests.
Check that Event Requests Appear in the Logs on Heroku
Now, let's review the application logs on Heroku to ensure it received the webhook event requests.
In the terminal:
Navigate back to the app directory if needed:
Bash
cd polis.js
View the logs:
Bash
heroku logs
Example of an event payload:
view rawwebhook-payload.zsh hosted with ❤ by GitHub
Note: One caveat of these logs is that they might not appear in the order the application actually wrote them out. However, the logs will still show that you received the webhook event requests.
Conclusion
You have successfully:
Deployed a Node.js webhook endpoint to Heroku.
Created and linked a Fulcrum webhook.
Verified webhook event data in your Heroku logs.
You have successfully completed this guide.
Next Step
Explore the Fulcrum Webhooks Developer Documentation to build more advanced integrations and automate your workflows.