Incoming Webhook – Create an Entry

Introduction

Incoming Webhooks are a feature of the Incoming Webhook Extension that allow external systems to create entries for forms.

If your workflow starts with a user-submitted form, you do not need this feature. You can use the Incoming Webhook Workflow Step instead to pause the workflow until an external system sends a request. See the link at the bottom of this page for further details.

How to Set Up an Incoming Webhook to Create an Entry

An Incoming Webhook creates an entry in a form when a POST request is received at an endpoint defined in the feed. The request body must be encoded as one of the following:

  • Form-data (application/x-www-form-urlencoded or multipart/form-data)
  • Form-data sent with a Content-Type header of application/json
  • Raw JSON with a Content-Type header of application/json

Requests sent without one of these encodings, or without a matching Content-Type header, will not be parsed and no entry will be created. See the Field Mapping page for details on how each format maps to form fields, including choice fields, sub-fields, and arrays.

An incoming Webhook can be created from the form settings page. Multiple webhooks can be added which will allow multiple systems to create entries for the same form.

Step Settings

Webhook URL

This is a read-only field which displays the URL for the Webhook. It contains the ID of the webhook plus the key. Copy and paste this URL into your external system.

Webhook name

Name this webhook so you can identify it in the list of webhooks for this form.

Key

Define a unique key for this webhook. This will make the URL difficult to guess and help to keep your webhook secure. If someone gets hold of this URL they would be able to create entries. However, if this is not secure enough for your use case then you should consider adding some custom code to verify the authenticity of the request. See the Helpscout example below for further details.

Field Values

Map the keys of the values in the request to fields on the form. See the Field Mapping page for further details, including how to handle checkboxes, multi-part fields, and array data.

Examples

Basic cURL Example

The quickest way to test a Create Entry webhook is with a cURL command. Replace [Your Webhook URL] with the URL from the Webhook URL setting, and update the field keys to match your Field Values mapping.

curl -X "POST" "[Your Webhook URL]" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d $'{
    "input_1": "Jane Doe",
    "input_2": "[email protected]",
    "input_3": "This is a value from the API request."
  }'

A successful request returns a 200 response and the new entry ID. If you get a 400 or 500 response, check that the Content-Type header matches the body encoding and that the field keys in the JSON match the keys defined in your Field Values mapping.

wp_remote_post Example

If the system creating the entry is itself a WordPress site, wp_remote_post() is the standard way to send the request without needing an external library.

$response = wp_remote_post( '[Your Webhook URL]', array(
   'headers' => array(
      'Content-Type' => 'application/json; charset=utf-8',
   ),
   'body' => wp_json_encode( array(
      'input_1' => 'Jane Doe',
      'input_2' => '[email protected]',
      'input_3' => 'This is a value from the API request.',
   ) ),
) );

if ( is_wp_error( $response ) ) {
   error_log( 'Incoming Webhook request failed: ' . $response->get_error_message() );
} else {
   $code = wp_remote_retrieve_response_code( $response );
   $body = wp_remote_retrieve_body( $response );
   error_log( "Incoming Webhook response ({$code}): {$body}" );
}

Helpscout Webhooks

This is a more specific example showing how an existing third-party system, HelpScout, can be configured to send its own webhook requests to an Incoming Webhook, including verifying the request’s authenticity. It will create an entry in HelpScout when a rating is received.


Once you have the Incoming Webhook URL you can add it to the Callback URL setting in your Helpscout Webhook app like this:

Every time you receive a rating in Helpscout, the webhook request will be sent to your Incoming Webhook URL and an entry will be created.

Once the entry has been created by the webhook, then the workflow will be triggered automatically. For example, you could add a notification step which sends an email if the rating is not “good”, and a Slack step which sends all the “good” ratings to your support team Slack channel.

Download the sample form: helpscout-ratings-webook.json

Helpscout includes a security feature for its webhooks so that you can verify the authenticity of the request by checking the hash. Here’s a snippet that will verify the request. You’ll need to add the HELPSCOUT_WEBHOOK_SECRET_KEY constant to your wp-config.php file and edit the feed ID.

// Define in wp-config.php
// define( 'HELPSCOUT_WEBHOOK_SECRET_KEY', 'the secret key' );

add_filter( 'gravityflowincomingwebhook_check_permissions', 'gravityflow_werify_helpscout_webhook', 10, 2 );

/**
 * Verify the authenticity of the Helpscout webhook.
 *
 * @param bool            $has_permission
 * @param WP_REST_Request $request
 *
 * @return bool
 */
function gravityflow_werify_helpscout_webhook( $has_permission, $request ) {

   // Replace 1 with the ID for the webhook you need to verify.
   if ( $request->get_param( 'feed_id' ) != 1 ) {
      // The request is not from Helpscout so don't override the permissions check.
      return $has_permission;
   }

   $signature = $request->get_header( 'X-HELPSCOUT-SIGNATURE' );

   $data = $request->get_body();

   $calculated = base64_encode( hash_hmac( 'sha1', $data, HELPSCOUT_WEBHOOK_SECRET_KEY, true ) );

   return $signature == $calculated;
}

Importing and Exporting

Incoming Webhooks are automatically exported and imported with the form.