You want to start using webhooks and we want to make getting started easier! So here’s a real-world example that walks you through the steps needed to see webhooks in action with your data. For someone with programming experience, it should be quick to set up.
This guide assumes you have:
- experience with developing and deploying web applications
- know-how of the following software:git a console/terminal program (e.g. iTerm 2)
- a Fulcrum plan that enables webhooks
- the proper webhooks roles & permissions to manage webhooks (e.g. you’re the organization owner)
Here’s an overview of the steps we’ll be working through.
- Deploy a simple Rails 4 application to Heroku.
- Create a webhook in Fulcrum to use this application.
- Create an app with data in Fulcrum.
- Check that we see those event requests in the Rails 4 application.
Deploy a Simple Rails 4 Application to Heroku
Heroku is a platform for hosting applications in the cloud. They’re well-known and have good guides for new users. It’s possible to deploy a small application to Heroku for free. That’s what we’re working toward.
First, you’ll need a Heroku account.
- Follow the steps in their quick start guide to create an account , install the Heroku tool belt, and log in to your account using the toolbelt.
Deploy the Application
In the course of building the webhooks functionality, we created an application for testing. It’s called fulcrum-webhook-sample-rails4. The application receives HTTP POST requests and writes the contents to its database. It’s the application we’ll set up as a webhook endpoint.
In your terminal:
- Navigate to a directory where you want to keep the source code.
git clone https://github.com/spatialnetworks/fulcrum-webhook-sample-rails4.git
ruby -e "require 'securerandom'; puts SecureRandom.hex(128);"Use the string output from this command in the next command.
heroku config:set SECRET_TOKEN=<string from previous command output>
git push heroku master
heroku domainsRemember the output from here since it will be the URL of the webhook we create next.
heroku run rake db:migrate
Test the Application
In your terminal:
This will open the site in your browser. The page should say
Listing Webhook Event Requests.
Create a Webhook in Fulcrum to use this Application
In your browser:
- Log into your account on Fulcrum.
- Click the cog in the upper right of the page.
- If you were in another organization, on the left menu, click the name of the organization you’re interested in.
API Webhooksin the list of links for that org’s settings.
Rails 4 Sample Endpointas the webhook’s name.
- Enter your heroku application’s URL as the webhook’s URL.This is the output from the
heroku domainscommand above.
Create an App with Data in Fulcrum
Now that the webhook has been created, we can start using it.
- Click on the Fulcrum logo in the top left.
- Click the organization context drop down at the top right.
- Make sure you’re in the right organization.
Design a new app.
- Drag a
Textfield into the Field Settings area.
- Give it the label
- Name the app
- Click the Webhook Test app in the list of your apps.
- Click the green
+sign to create a new record.
- Click anywhere on the map to give the record a location.
First Recordas the Name for this record.
You’ve created a new app and record within Fulcrum. Since we have an active webhook within our organization, an event is created for both the form and record we made. Each event generates requests for each of the webhooks in our org. Since we only have one webhook now, one request is made for the form and one for the record. Those requests are made to the webhook’s URL automatically. So now, we should expect that our Rails 4 app has received the requests. And we can check that next.
Check that We See those Event Requests in the Rails 4 Application
Now, let’s check out the application on Heroku to make sure it received the webhook events requests.
In the terminal:
- Navigate back to the
fulcrum-webhook-sample-rails4folder, if necessary.
- In the web page that opens, we should see the contents of two requests.
- The first will be the event request data for the form create.
- The second will be the event request data for the record create.
We’ve successfully set up the webhook endpoint, created the webhook in Fulcrum, and seen that they are connected.
Give yourself a pat on the back!
Now, you can check out the Webhooks Developer Documentation and begin building more sophisticated applications to extend Fulcrum!