Forms: Add form response webhooks (#46059)

* Add form webhook settings panel

Added under a feature flag to test the webhook implementation.

* Add a form webhook class

This is an exploratory commit where I'm using a different class, based
on the Post_To_Url one, to process and dispatch the webhooks on form
submission.

* changelog

* Add webhook id input field

I added the webhook id input to the settings section to explore how we
could use it for advanced users that would like to programmatically
manipulate form data before sending it to webhook. For that, we'll need
to expose a filter which I'll bring in a follow up commit.

* Add jetpack_forms_before_webhook_request

I'm adding this filter here to allow developers to intercept and modify
the form data that I'm sending in the webhook request. This should give
enough fleixibility to advanced users.

* Log response and errors to post meta table

* Fix param type in documentation

* Fix JetpackContactFormAttributes type declaration

* Fix unit test

* Forms: add comprehensive webhook functionality (#46099)

* let salesforce process remain as it was. Split (just in case) postToUrl and migrate it to a webhook

* add class consts for cleaner code

* create and validate webhook setup with class consts, ditch non matching formats/methods

* use class constants on request process

* invert filter params order so data is returned by default even when no filter is set

* add tests for Form_Webhooks class

* make phan happy on test files

* changelog

* Fix webhook method validation

* Forms: Add webhook logging and initialization flag (#46110)

* add logging for skipped webhooks

* only init webhooks class if webhooks are enabled

* changelog

* add tests for webhooks and contact form flags

* fix phan issues

* Add plan-based feature support for form webhooks (#46138)

* add form-webhooks support on free JP plans

* set flag form-webhooks based on current plan support

* consider both filter and feature flag for enabling webhook settings

* add webhooks feature support plans

* add changelogs

* add wpcomsh changelog

---------

Co-authored-by: Christian Gastrell <[email protected]>

Author: vianasw

projects/packages/forms/changelog/add-form-response-webhooks

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Forms: add form response webhook support.

projects/packages/forms/changelog/add-form-webhook-support

@@ -0,0 +1,4 @@
+Significance: minor
+Type: changed
+
+Enable form webhooks feature based on current plan support

projects/packages/forms/changelog/add-form-webhooks-skipped-logging

@@ -0,0 +1,4 @@
+Significance: patch
+Type: added
+
+Form Webhooks: add logging and filter flag for initialization

projects/packages/forms/changelog/add-forms-webhooks-prettyfication

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+Form Webhooks: clean up and consolidate webhooks to take over the unused-yet-present postToUrl

projects/packages/forms/src/blocks/contact-form/attributes.ts

@@ -85,4 +85,8 @@ export default {
 		type: 'array',
 		default: [],
 	},
+	webhooks: {
+		type: 'array',
+		default: [],
+	},
 };

projects/packages/forms/src/blocks/contact-form/class-contact-form-block.php

@@ -62,6 +62,7 @@ public static function register_block() {
 	public static function register_feature( $features ) {
 		// Features that are only available to users with a paid plan.
 		$features['multistep-form'] = Current_Plan::supports( 'multistep-form' );
+		$features['form-webhooks']  = Current_Plan::supports( 'form-webhooks' );
 
 		return $features;
 	}

projects/packages/forms/src/blocks/contact-form/components/webhooks-settings.js

@@ -0,0 +1,100 @@
+import { TextControl, ToggleControl, ExternalLink } from '@wordpress/components';
+import { useState, useEffect, createInterpolateElement } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+
+const WebhooksSettings = ( { setAttributes, webhooks } ) => {
+	// For now, we only support one webhook, but the data structure supports multiple
+	const firstWebhook = webhooks?.[ 0 ] || null;
+
+	const [ localWebhookId, setLocalWebhookId ] = useState( firstWebhook?.webhook_id || '' );
+	const [ localWebhookUrl, setLocalWebhookUrl ] = useState( firstWebhook?.url || '' );
+	const [ localWebhookEnabled, setLocalWebhookEnabled ] = useState(
+		firstWebhook?.enabled || false
+	);
+
+	// Sync local state with attributes when webhook changes
+	useEffect( () => {
+		if ( firstWebhook ) {
+			setLocalWebhookId( firstWebhook.webhook_id || '' );
+			setLocalWebhookUrl( firstWebhook.url || '' );
+			setLocalWebhookEnabled( firstWebhook.enabled || false );
+		}
+	}, [ firstWebhook ] );
+
+	const updateWebhook = ( id, url, enabled ) => {
+		if ( ! url && ! enabled ) {
+			// If URL is empty and webhook is disabled, remove it from the array
+			setAttributes( { webhooks: [] } );
+			return;
+		}
+
+		const webhook = {
+			webhook_id: id || '',
+			url: url || '',
+			format: 'json', // Default to json, no UI for changing this yet
+			method: 'POST', // Default to POST, no UI for changing this yet
+			enabled: enabled,
+		};
+
+		setAttributes( { webhooks: [ webhook ] } );
+	};
+
+	return (
+		<>
+			<ToggleControl
+				label={ __( 'Enable webhook', 'jetpack-forms' ) }
+				help={ createInterpolateElement(
+					__(
+						'Send form submission data to an external URL. <webhookDocsLink>Learn more about webhooks.</webhookDocsLink>',
+						'jetpack-forms'
+					),
+					{
+						webhookDocsLink: (
+							<ExternalLink href="https://jetpack.com/support/jetpack-forms/webhooks/" />
+						),
+					}
+				) }
+				checked={ localWebhookEnabled }
+				onChange={ value => {
+					setLocalWebhookEnabled( value );
+					updateWebhook( localWebhookId, localWebhookUrl, value );
+				} }
+				__nextHasNoMarginBottom={ true }
+			/>
+			{ localWebhookEnabled && (
+				<>
+					<TextControl
+						label={ __( 'Webhook ID', 'jetpack-forms' ) }
+						value={ localWebhookId }
+						onChange={ value => {
+							setLocalWebhookId( value );
+							updateWebhook( value, localWebhookUrl, localWebhookEnabled );
+						} }
+						placeholder="webhook-1"
+						help={ __( 'A unique identifier for this webhook.', 'jetpack-forms' ) }
+						__nextHasNoMarginBottom={ true }
+						__next40pxDefaultSize={ true }
+					/>
+					<TextControl
+						label={ __( 'Webhook URL', 'jetpack-forms' ) }
+						value={ localWebhookUrl }
+						onChange={ value => {
+							setLocalWebhookUrl( value );
+							updateWebhook( localWebhookId, value, localWebhookEnabled );
+						} }
+						placeholder="https://example.com/webhook"
+						help={ __(
+							'Enter the URL where form submission data should be sent.',
+							'jetpack-forms'
+						) }
+						type="url"
+						__nextHasNoMarginBottom={ true }
+						__next40pxDefaultSize={ true }
+					/>
+				</>
+			) }
+		</>
+	);
+};
+
+export default WebhooksSettings;

projects/packages/forms/src/blocks/contact-form/edit.tsx

@@ -2,7 +2,7 @@
  * External dependencies
  */
 import { ThemeProvider } from '@automattic/jetpack-components';
-import { useModuleStatus } from '@automattic/jetpack-shared-extension-utils';
+import { useModuleStatus, hasFeatureFlag } from '@automattic/jetpack-shared-extension-utils';
 import {
 	URLInput,
 	InspectorAdvancedControls,
@@ -50,6 +50,7 @@ import { childBlocks } from './child-blocks.js';
 import { ContactFormPlaceholder } from './components/jetpack-contact-form-placeholder.js';
 import ContactFormSkeletonLoader from './components/jetpack-contact-form-skeleton-loader.js';
 import NotificationsSettings from './components/notifications-settings.js';
+import WebhooksSettings from './components/webhooks-settings.js';
 import useFormBlockDefaults from './shared/hooks/use-form-block-defaults.js';
 import VariationPicker from './variation-picker.js';
 import './util/form-styles.js';
@@ -118,6 +119,14 @@ type CustomThankyouType =
 	| 'message' // custom message
 	| 'redirect'; // redirect to a new URL
 
+type Webhook = {
+	webhook_id: string;
+	url: string;
+	format: 'urlencoded' | 'json';
+	method: 'POST' | 'GET' | 'PUT';
+	enabled: boolean;
+};
+
 type JetpackContactFormAttributes = {
 	to: string;
 	subject: string;
@@ -133,7 +142,9 @@ type JetpackContactFormAttributes = {
 	disableGoBack: boolean;
 	disableSummary: boolean;
 	notificationRecipients: string[];
+	webhooks: Webhook[];
 };
+
 type JetpackContactFormEditProps = {
 	name: string;
 	attributes: JetpackContactFormAttributes;
@@ -166,8 +177,10 @@ function JetpackContactFormEdit( {
 		disableGoBack,
 		disableSummary,
 		notificationRecipients,
+		webhooks,
 	} = attributes;
 	const showFormIntegrations = useConfigValue( 'isIntegrationsEnabled' );
+	const showWebhooks = useConfigValue( 'isWebhooksEnabled' ) && hasFeatureFlag( 'form-webhooks' );
 	const instanceId = useInstanceId( JetpackContactFormEdit );
 
 	// Backward compatibility for the deprecated customThankyou attribute.
@@ -913,6 +926,15 @@ function JetpackContactFormEdit( {
 							<IntegrationControls attributes={ attributes } setAttributes={ setAttributes } />
 						</Suspense>
 					) }
+					{ showWebhooks && (
+						<PanelBody
+							title={ __( 'Webhooks', 'jetpack-forms' ) }
+							className="jetpack-contact-form__panel"
+							initialOpen={ false }
+						>
+							<WebhooksSettings webhooks={ webhooks } setAttributes={ setAttributes } />
+						</PanelBody>
+					) }
 					<PanelBody
 						title={ __( 'Responses storage', 'jetpack-forms' ) }
 						className="jetpack-contact-form__panel jetpack-contact-form__responses-storage-panel"

projects/packages/forms/src/class-jetpack-forms.php

@@ -124,4 +124,18 @@ public static function is_integrations_enabled() {
 		 */
 		return apply_filters( 'jetpack_forms_is_integrations_enabled', true );
 	}
+
+	/**
+	 * Returns true if webhooks are enabled.
+	 *
+	 * @return boolean
+	 */
+	public static function is_webhooks_enabled() {
+		/**
+		 * Whether to enable webhooks for Jetpack Forms.
+		 *
+		 * @param bool false Whether webhooks should be enabled. Default false.
+		 */
+		return apply_filters( 'jetpack_forms_webhooks_enabled', false );
+	}
 }

projects/packages/forms/src/contact-form/class-contact-form-endpoint.php

@@ -1494,6 +1494,7 @@ public function get_forms_config( WP_REST_Request $request ) { // phpcs:ignore V
 			'siteURL'                 => ( new Status() )->get_site_suffix(),
 			'hasFeedback'             => ( new Forms_Dashboard() )->has_feedback(),
 			'isIntegrationsEnabled'   => Jetpack_Forms::is_integrations_enabled(),
+			'isWebhooksEnabled'       => Jetpack_Forms::is_webhooks_enabled(),
 			'dashboardURL'            => Forms_Dashboard::get_forms_admin_url(),
 			// New data.
 			'canInstallPlugins'       => current_user_can( 'install_plugins' ),