blackbricksoftware / gravityforms-civicrm-form-processor
WordPress plugin that makes Gravity Forms webhooks to CiviCRM easier.
Package info
github.com/blackbricksoftware/gravityforms-civicrm-form-processor
Type:wordpress-plugin
pkg:composer/blackbricksoftware/gravityforms-civicrm-form-processor
Requires
- php: ^8.2
- blackbricksoftware/wp-artifact-updater: ^1.5.0
- illuminate/support: ^8.0 || ^9.0 || ^10.0 || ^11.0 || ^12.0 || ^13.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-07 05:30:12 UTC
README
Send remote requests to CiviCRM with Gravity Forms Webhooks. This can be done directly to the CiviCRM API or via Form Processor.
What does this extension do?
TL;DR; This extension makes it easier to send data from a Gravity Form to a remote CiviCRM installation.
The CiviCRM REST REST API consumed data via encoded JSON a HTTP form post. In APIv3, this variable is json, in APIv4 this variable is params. Out of the box, the Gravity Forms Webhooks extension does not support structured JSON or combining data encodings like this (i.e. a Request Format of FORM containing encoded JSON).
This extension also add the option to send an email notification when a webhook to CiviCRM fails.
How do I get this up and running?
- (Recommended) Install and configure the AuthX extension that comes with CiviCRM. This gives many options for authentication mechanisms.
- Configure authentication rules and mechanisms (Administer -> Administration Console -> Authentication). The defaults are probably okay.
- (Recommended) Install API Key Extension
- (Recommended) Install the Action Provider and Form Processor extensions. These are not necessary, but they do provide quite a bit for flexibility in how data from Gravity Forms is processed compared to directly using the CiviCRM API.
- Create a new contact to function as the creator of any data coming in from Gravity Forms; there are a number of ways to authenticate with this contact. This contact might need an attached user account if the Gravity Forms requests will require specific permissions.
- Add an API Key to this contact.
- Not the API Key and Site Key (if using Site Key Guard in AuthX)
- Determine the CiviCRM API end point. There are a number of options: legacy, modern, CMS specific... In this example, we will use the modern ones.
- Wordpress
- Drupal
- Joomla
- https://civicrm.example.org/index.php?option=com_civicrm&format=raw&task=civicrm/ajax/rest
- (with customization) https://civicrm.example.org/civicrm/ajax/rest
- To use the clean version of the URL with Joomla, add these likes to the
.htaccessfile user the `` section
# Provide a consistant way to access civicrm content RewriteCond %{REQUEST_URI} ^/civicrm/(.*)$ RewriteRule ^(.*)$ index.php?option=com_civicrm&format=raw&task=$1 [QSA] - To use the clean version of the URL with Joomla, add these likes to the
- Create a Gravity Form
- Go to the Form Settings and add a Webhook
- Add the CiviCRM API end point to the Request URL with
entity(e.g. Contact) andaction(e.g. create) as query string parameters. - Choose
POSTfor the Request Method andFORMfor the Request Format. - Enable the CiviCRM API Format
- Add Request Headers to provide authentication with CiviCRM. Out of the box, three are necessary with AuthX.
Authorization: Bearer **API_KEY**X-Civi-Key: **SITE_KEY**X-Requested-With: XMLHttpRequest
- Under the Request Body choose to Select Fields.
- Any normal key field will be directly passed to CiviCRM
- Any key that needs pass to CiviCRM in the
json(v3) orparams(v4) JSON encoded form value, prependjson.orparams.respectively. For example, to send CiviCRM a first name in the request, create the keyjson.first_name.
- Add the CiviCRM API end point to the Request URL with
Other features
Besides the CiviCRM API format, the plugin adds these to Gravity Forms.
On each form's settings (Form Settings › Additional Webhooks settings):
- Delete entries after Webhook are completed successfully: delete the entry once all of the form's active webhooks have succeeded. Useful for data security.
- Number of times to try submitting a Webhook: Gravity Forms tries a webhook once by default; this lets it try several times.
On each webhook's settings (Form Settings › Webhooks › the webhook):
- CiviCRM Webhook Failure Notification: email someone when the webhook fails: CiviCRM can't be reached, answers with an HTTP status other than 200, answers with something that isn't JSON, or reports an API error. Set who it goes to, who it's from, a BCC and the subject.
- Request Timeout (seconds): how long to wait for CiviCRM before giving up on this webhook. WordPress's default is 5 seconds, which a busy CiviCRM can exceed.
- Max Attempts: how many times to try this webhook, overriding the form's "Number of times to try submitting a Webhook".
Sending webhooks again. Gravity Forms sends a webhook once, when an entry comes in, and has no way to send it again. If CiviCRM was down, or a webhook was turned off at the time:
- For one entry: open it (Forms › Entries › the entry). Its Webhooks box lists the form's active webhooks with how each last went for that entry. Tick one or more and press Send: they go out straight away, the box shows each result (sent, or what went wrong), and a note on the entry records who sent them. It sends even if a webhook was already sent, or if its condition doesn't match the entry (marked "condition not met").
- For many entries: select them on the Entries list, choose Send webhooks again from the bulk actions and Apply. Each entry's webhooks are queued just as on submission (its active webhooks whose conditions match it), and Gravity Forms sends them in the background with its usual retries. Each entry's notes show how they went.
Either way, everything that applies to a webhook applies here too, including the failure email and "Delete entries after Webhook are completed successfully". Users who can edit entries can use them.
Installing
Requires PHP 8.2 or later, and Gravity Forms with its Webhooks add-on.
Download gravityforms-civicrm-form-processor-vX.Y.Z.zip from the latest release and upload it on Plugins › Add New › Upload Plugin. Use that zip, not GitHub's "Source code" archives: those have no vendor/ folder, so the plugin can't load and does nothing.
The plugin is also on Packagist as blackbricksoftware/gravityforms-civicrm-form-processor, for sites managed with composer.
Updates
New versions are published as GitHub releases, and WordPress offers them on the Plugins page like any other plugin's update. They are never installed on their own unless you turn on auto-updates for this plugin there. WordPress checks a few times a day; Dashboard › Updates › Check again checks GitHub straight away. Updates install into whichever folder the plugin is in.
- Sites where a deploy owns the plugins (composer, git) should set WordPress's own
define('DISALLOW_FILE_MODS', true);, which removes the update notice, "Update now" and auto-updates for every plugin. Composer-managed sites update withcomposer update blackbricksoftware/gravityforms-civicrm-form-processor, git checkouts withgit pullandcomposer install --no-dev. - Multisite: network-activate the plugin, or at least activate it on the main site. WordPress only checks for updates there.
- What a site must reach: WordPress asks
api.wordpress.orgabout all plugins first, and stops if that fails, before it asks about this one. Thenapi.github.comfor the newest release, andgithub.comandrelease-assets.githubusercontent.comto download it. No token is used; the requests carry WordPress's usual user agent, which names the site. - What it trusts: each site installs the zip attached to the repository's latest GitHub release, over HTTPS. Anyone who can publish releases in this repository can therefore ship code to every site with auto-updates on.
Upgrading from 2.0.0 or earlier is a manual install, once, since those versions can't update themselves:
- Upload the new release's zip as above.
- Click Activate Plugin on the result screen. This deactivates the old copy for you.
- Click Delete the old copy in the notice on the Plugins page.
The release zips for 1.0.1–2.0.0 had no folder inside them, so a site that uploaded one has the plugin in a folder named after the zip (gravity_forms_civicrm_form_processor, or on WordPress 7.1.4 and later that name plus random characters). The new version's folder is gravityforms-civicrm-form-processor, so WordPress installs it beside the old copy instead of replacing it, and the Plugins page lists the plugin twice until the old one is deleted. Nothing is lost: the plugin's form and webhook settings are stored by Gravity Forms. (2.1.0 doesn't deactivate the old copy itself: if you installed 2.1.0 this way, deactivate and delete the v2.0.0 copy by hand.) Composer and git installs update as above instead.
Recovering entries deleted after a failed webhook
Up to 2.2.0, with Gravity Forms 3.0.2 or later on a live site (WP_DEBUG off), a webhook CiviCRM answered with a failure was recorded as sent, and "Delete entries after Webhook are completed successfully" deleted its entry. 2.3.0 fixes that. Each such entry's failure email (if the webhook had one) holds a full copy of it, the $entry part, and bin/recover-entries.php puts those entries back under their original ids:
- Copy each email's text (the whole email, or its
$entrypart) into.txtfiles in a folder, for example.working/at the repository's root, which git ignores. A file may hold several entries. If Gmail shows "View entire message", open that first, or the copy is cut short. The email's HTML works too. - Put the folder and
bin/recover-entries.phpon the server outside the site's folder, readable only by you: for example~/recover_entries/besidepublic_html/, holding the script and the folderbackups/. The script reads every file in that folder, so put nothing else in it. - Back up the entry tables, from
~/recover_entries/:tables=$(wp --path=../public_html db tables '*gf_entry*' --all-tables-with-prefix --format=csv) && echo "$tables" && wp --path=../public_html db export --tables="$tables" ~/recover_entries/entries-before.sql. It names the three tables it backs up,…gf_entry,…gf_entry_metaand…gf_entry_notes, and holds personal data too. (Without--all-tables-with-prefix,wp db tableslooks only at WordPress's own tables, finds none, and the export gets no list of tables.) - A dry run, from
~/recover_entries/:wp --path=../public_html eval-file recover-entries.php backups. It names the site and database, then each entry by id, form, date and number of field values. It checks each copy against its form: one it can't trust (cut off, wrapped, two copies that disagree) is marked FAILED, with why, and notes list what can't be put back (values of fields no longer on the form, uploaded files). It changes nothing. wp --path=../public_html eval-file recover-entries.php backups apply 1681-1710puts them back. Each entry is put back under its own id in one transaction, then read back and compared with the copy: if anything differs or goes wrong, nothing of it is kept. It never changes an entry that exists, so it is safe to run again; it sends nothing; each entry it puts back gets a note saying so. With a range, it also lists the ids in it that have no copy and aren't on the site.- Once the cause of the failure is fixed, select the entries on the Entries list and use Send webhooks again. It sends every active webhook of the form whose conditions match, including any that had succeeded before the entry was deleted (to send only one, use the Webhooks box on the entry's page). And with "Delete entries after Webhooks are completed successfully" on, each entry is deleted again once its webhooks succeed: turn that off first to keep them until you have checked CiviCRM.
- Delete
~/recover_entries/, backup included, from the server.
The script prints only ids, form ids, dates, field ids and counts, never what was submitted.
Releasing
- Set the version in the plugin header,
Version: X.Y.Z, with nov(WordPress compares it as written, and PHP sortsv2.1.0below2.1.0). - Add a
# vX.Y.Z (YYYY-MM-DD)entry at the top ofCHANGELOG.md. It becomes the release notes. - Commit, then tag and push:
git tag vX.Y.Z && git push origin vX.Y.Z. Tag only commits that have.github/workflows/build.yml; a tag on a commit from before 2.1.0 runs that commit's old workflow.
The Build workflow builds the zip, tests it in a throwaway WordPress, and publishes that same zip to the tag's GitHub release. It refuses to build if the header, the changelog and the tag disagree, and never replaces a zip it has uploaded, even on a draft: to fix a release, release a new version. Sites see the release once GitHub marks it Latest, which the workflow does unless a higher tag exists.
Raising Requires PHP isn't enforced for sites that update in place: the update WordPress is offered carries no PHP requirement, so the auto-updater installs it on an older PHP. Only uploads, activation and "Update now" on the Plugins page check the new header.
To build locally: bin/build.sh (needs PHP 8.2, composer and zip) writes dist/gravityforms-civicrm-form-processor-vX.Y.Z.zip. To test: tests/run.sh (needs PHP with pdo_sqlite, WP-CLI, curl, unzip, zip, perl and composer) builds the zip itself, replacing dist/, installs it in a WordPress downloaded into .sandbox/, and tests the updates end to end. GFCFP_TEST_ZIP=path/to.zip tests/run.sh tests a zip you already have. The checks that need Gravity Forms (sending webhooks again, and how a failed webhook is handled) use a licensed copy: GFCFP_TEST_GF_DIR=~/Downloads (a folder holding gravityforms_*.zip and gravityformswebhooks_*.zip), or a licence key in GFCFP_TEST_GF_KEY or in the git-ignored file gravity_license_key at the repository's root, with which the newest versions are downloaded. Without one they are skipped. Some of them click through the pages in headless Chrome or Chromium (with Node), found on the PATH or named in GFCFP_TEST_CHROME, and are skipped without one. CI downloads them with the repository secret GRAVITY_FORMS_LICENSE_KEY and requires them on pushes and tags; pull requests from forks get no secrets, so they skip them.


