Incoming Webhook

The Incoming Webhook Extension is used to hold entries on a step until a trigger is received from an external application.

IMPORTANT: This step should only be used if the server has an SSL certificate installed as the API Secret is sent on every request.

Adding an Incoming Webhook Step

  1. Select Incoming Webhook as the step type.
  2. Enter a name for your application. This is just informational.
  3. Enter a unique API Key or accept the default value. The API key is used to authenticate each request. This value should generally not be changed after saving. Warning: if there are any entries on this step then changing this setting will result in the entries getting stuck in the workflow and unable to proceed.
  4. Enter a unique API Secret which will be used to authenticate the request. It's good practice to change this secret periodically.
  5. Determine if you want the step to map any values from the incoming request into field values in the entry.

Once an entry hits an Incoming Webhook step it waits until an authenticated request is received.

The Webhook URL

The Incoming Webhook extension listens for POST request to URLs with the following format:

[domain]/[api base]/entries/[Entry ID]/workflow-webhooks

Version 1 and 2 of the Gravity Forms Web/REST API are supported.

For version 1 of the Gravity Forms Web API (not recommended): 
http://local.wordpress.dev/gravityformsapi/entries/802/workflow-hooks

For Version 2 of the Gravity Forms Web API - using WP API routing (recommended) 
http://local.wordpress.dev/wp-json/gf/v2/entries/802/workflow-hooks

The following params should be sent in the POST request either in the URL or body: 
workflow-api-key 
workflow-api-secret 

Example request:

Response:

You can also send the parameters in the URL like this:

http://local.wordpress.dev/wp-json/gf/v2/entries/802/workflow-hooks/?workflow-api-key=xxxxxxx&workflow-api-secret=xxxxxxxx

Request Field Mapping 

As of Gravity Flow Incoming Webhook version 1.1 the step settings include an option for Field Mapping which opens up many more potential integration options for Gravity Flow. If you are familiar with the Outgoing Webhook step setup you will find this new setting very familiar.

  • The default (None) will process the workflow onto the next step as soon as a valid request is received. This is valuable when your entry workflow only needs to know that a 3rd party system (or other form using an Outgoing webhook step) has completed a task before proceeding.
  • The new setting (Select Fields) lets you define a field mapping between a request key and entry field. When a valid request is received containing data in the body as either form-data or application/json, the mapped field values will attempt to be stored into the entry. This enables 3rd party systems which have updated data for the entry can pass it in via the incoming webhook step.

Field Mapping Notes:

  • Request Type
    The system which is sending data to the incoming webhook step in one of 3 formats. In all cases the workflow-api-key and workflow-api-secret must be included in order to authenticate the request.
         - POST with form-data in the body of the request
         - POST with form-data in the body of the request with a Content-Type header = application/json
         - POST with raw JSON in the body of the request with a Content-Type header = application/json
  • Request Sanitization not Request Validation
    All incoming request values are sanitized based on their field type regardless of whether you use version 1 or 2 of the Gravity Forms Web/REST API. This prevents script injections and other technically bad data from being submit through the incoming webhook step field mapping to your form entries. However, it does not validate the request values submit for required status or format. 

    What does that mean exactly? If you have a dropdown field type set as required with options of A, B, C, D or E, mapping that field for a request 
         - WOULD prevent "<script>alert('Doing bad things')</script>" from being stored to DB in a bad format. 
         - WOULD NOT prevent "Banana" from being stored. 

    If you need the API / step to validate request values, or source, it is suggested you use version 2 of the Gravity Forms API and refer to the  WordPress Rest API Handbook on extending the API or helpful blog posts on validating options with it.
  • Choice and Complex Field Types
    Some field types that can have multiple selections (ex. checkboxes) or do have sub-fields (ex. address) can have a request values mapped to the entire field or individual data elements. The following step settings field values and JSON show how they could be set as part of a raw JSON request. 

    {"checkboxes": [{"id":"4.1","value":"Alberta"},{"id":"4.2","value":"British Columbia"},{"id":"4.9","value":"Ontario"}], "single-checkbox": "Alberta", "multiselect": ["Alberta","British Columbia","Ontario"], "name-full": [{"id":"11.3","value":"Mickey"},{"id":"11.6","value":"Mantle"}], "name-middle": "Baseball", "address-full":[{"id":"15.1","value":"Apt 1"},{"id":"15.2","value":"2nd Street"}], "address-city": "New York"}<br> 	
  • Unavailable Field Types
    The majority of field types in the standard, advanced and workflow sections of the form editor are available for request mapping. A few, listed below, are not available at this time. Please  contact us if you have a use case that would benefit from them being added to a future release of the add-on. 
         - File Uploads 
         - Any Post Fields (Title, Content, Excerpt, Tags, Category, Images, Custom Field) 
         - Any Pricing Fields (Product, Quantity, Options, Shipping, Total 

Example In Action - Webhook Demo Help Desk

You can download the webhook-demo-helpdesk.zip which contain the following files to help you get started:

  • gravityforms-export-webhook-demo.json
    An exported form that simulates a help desk website form. Entry details are sent via an outgoing webhook step to a back-end / 3rd party system for processing (simulated by a requestbin) and an incoming webhook step awaits the response which you can simulate with...
  • Webhook Web Help Desk.postman_collection.json
    Postman is an API test wondertool! After importing the collection to Postman and making a few small changes to tailor to your test environment, you will be able to make the incoming request and complete the workflow.
  • webhook.php / webhook.html
    An example call to complete the incoming webhook step (generated via Postman) via PHP or Javascript

How to setup the demo in your local environment?

  1. Download webhook-demo-helpdesk.zip and extract on your local PC.
  2. Access your test environment and use the Forms > Import section to import the gravityforms-export-webhook-demo.json file.
    The new form will be named "Webhook Web Help Desk". See Gravity Forms instructions on importing forms if needed.
  3. (Optional) Modify the outgoing step on the new form 
    The demo is setup with webhook URL pointing to a requestbin that should respond if you don't make any changes but limits your ability to see the request/response information of the outgoing step if you do not update to match your test environment tooling. See requestb.in for more setup info or should the demo fail in your environment during the outgoing webhook step.
  4. Preview the form and create a test entry. Note the entry ID which is displayed in the confirmation screen.
  5. Submit an incoming request via whatever API call method you prefer.
    The included Postman collection (and webhook .php / .html) are setup with the API call to http://local.test/wp-json/gf/v2/entries/6/workflow-hooks
    You will need to modify them to change the change the domain (local.test) and the test entry ID (6) to match your environment / test case.

  6. Access the Workflow Status page to see that your entry workflow has been completed and the resolution, status and discussion fields updated.

Still need help? Contact Support Contact Support