Webhooks

The Webhooks add-on needs to be installed and activated to see the features mentioned in this this documentation.

Webhooks are a way to send simple POST or GET data containing form information when a form is submitted.  This is done within the Ninja Forms actions system and requires creating a new action to get started.  For more information about what webhooks are and how they work, check out the wiki article here.

Note: While we love helping Webhooks users integrate with all the services, our support for integration is limited to making sure that we send data as it’s laid out in the settings. If you have questions about a particular service, or how to post to a specific service, you should contact that service’s support. Most services that accept webhooks have great API documentation to make the process as painless as possible. Please see developer.ninjaforms.com for further technical resources as well.

Create a Webhooks Action

To create a new action, go to the “Emails and Actions” tab of your form builder.

Emails and Actions

Then, once looking at your list of current actions, click “Add New Action.”

Add New Action

When the “Actions” drawer opens, choose “Webhooks.”

Choose Webhooks

That’s it!  You’re ready to configure your Webhook action!

Configuring Your Webhooks Action

Below is the Webhooks configuration drawer.  We will cover each option in detail.

Webhooks Settings

  • Remote URL – The URL to which you will be submitting data.
  • Remote Method
  • ARGS
    • Key – The “name” your chosen URL will use to understand the field data you’re sending
    • Field – The field containing the data you wish to send to your “Remote URL”
  • Advanced
    • Encode ARGS as a JSON string
    • Run in Debug Mode – Data will submit to your endpoint in a verbose manner.  Useful for troubleshooting as errors from the API may be shown after form submission.

 

Example Usage

Add Key/Field Pairs

To add a new key/field pair, click “Add New”

Key/Field Pairs

Once your key value pairs are configured, your form is good to go!  Using the default Contact Form included in Ninja Forms, I have completed the key/value pairs for examples below.  Let’s assume the form data we are working with is as follows from the contact form:

  • Name – “Ninja Zach”
  • Email – “ninja@ninjaforms.com”
  • Message – “Hey man, I really love the team’s new Webhooks extension!  Way to go!”

Map Your Key/Value Pairs

Set a Static Key Value

To connect to my imaginary API, I need to also provide an API key (mine is abcdef123456).  My service expects the my API key to be called “id”, so that is the key name I will assign.  All we need to do is use “id” as the key, and copy our API key into the “field” box.

Static Value attached to a key

Map Field Data to a Key Value

My sample API expects a name, an email address, and a message.  For my API, they are called “name”, “email”, and “message” respectively.  Map field values by using the list “merge tag” icon on the far right of fields in the “Field” list

Mapping field values to keys

Once your field values are mapped, your pairs will look like this:

finished key mapping

Example Outputs

GET Requests

As JSON string, single variable 'myVar'
Remote URL: 
https://mytestapi.com/endpoint/?myvar=%7B%22id%22%3A%22abcdef123456%22%2C%22name%22%3A%22Zach%22%2C%22email%22%3A%22zach%40ninjaforms.com%22%2C%22message%22%3A%22Here+is+my+message+text.%22%7D
As JSON string
Remote URL: 
https://mytestapi.com/endpoint/?myvar=%7B%22id%22%3A%22abcdef123456%22%2C%22name%22%3A%22Zach%22%2C%22email%22%3A%22zach%40ninjaforms.com%22%2C%22message%22%3A%22Here+is+my+message+text.%22%7D

POST Submissions

As JSON string, single variable 'myVar'
Remote URL:
https://mytestapi.com/endpoint/
Args:
myvar => {"id":"abcdef123456","name":"Zach","email":"zach@ninjaforms.com","message":"This is my message box text."}
As JSON string
Remote URL:
https://mytestapi.com/endpoint/
Args:
{"id":"abcdef123456","name":"Zach","email":"zach@ninjaforms.com","message":"This is my message text."}

You can test your Webhook using the Beeceptor Service

How helpful was this documentation?

Gold Star Green Light Yellow Light Red Light
Very helpful Helpful Unclear/Unhelpful Not helpful at all