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 submit.  This is done within the Ninja Forms “Acitons” 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:  Please do not contact our support team with issues related to connecting to a specific API.  This is a very advanced addon, and though we know it works for most webhooks we can’t guarantee compatibility with every possible external service.  Please feel free to contact us with suggestions for improvement, feature requests, and bug reports…but our support team will not be able to assist with individual API connections to whatever service you are working with.  We strongly suggest contacting your service vendor for assistance with using their API’s.

Create a New 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 teams 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'
As JSON string

POST Submissions

As JSON string, single variable 'myVar'
As JSON string