Gravity Forms Webhooks: Complete Guide to API Integration (2026)

Gravity Forms can connect to hundreds of tools using dedicated add-ons, but what happens when the service you need is not on the list? The Webhooks Add-On fills that gap. It sends form submission data to any external URL via HTTP, giving you a direct line from your WordPress forms to virtually any API, automation platform, or custom application.

Whether you want to push lead data into a CRM that lacks an official Gravity Forms add-on, feed submissions into an n8n or Make workflow, or sync entries with a custom internal tool, webhooks make it possible without writing a single plugin. This guide walks through every step: prerequisites, feed configuration, authentication, JSON formatting, real-world integration examples, debugging, and the advanced filters that let you reshape outgoing data to match any API’s expectations.

What Webhooks Are and Why They Matter for Form Integration

A webhook is a user-defined HTTP callback. Instead of your application constantly polling an external service to ask “has anything changed?” a webhook flips the model: when a specific event occurs, such as a form submission, WordPress fires an HTTP request to a URL you specify, delivering data in real time.

For Gravity Forms users, this event-driven approach means the moment someone submits a form, the Webhooks Add-On packages the entry data and sends it to your chosen endpoint. No cron delays, no manual exports, no middleware required (though middleware like n8n can certainly extend what you do with the data).

The practical difference compared to dedicated add-ons like the HubSpot or Salesforce CRM integrations is flexibility. Dedicated add-ons are purpose-built for a single service. Webhooks are service-agnostic: if the destination speaks HTTP, you can connect to it.

Prerequisites and Licensing

Before you configure anything, confirm that the following requirements are met:

Gravity Forms Elite or Nonprofit license — the Webhooks Add-On is not available on Basic or Pro plans. If you are currently on a lower tier, Gravity Forms lets you upgrade and pay only the prorated difference.
WordPress 6.2 or higher and PHP 7.4+ (PHP 8.x recommended).
The Webhooks Add-On installed and activated — navigate to Forms > Add-Ons, locate the Webhooks Add-On, and click Install then Activate. If it does not appear in your list, your license does not include it.
An external endpoint ready to receive data — this could be a direct API URL, an automation platform webhook URL, or a testing service like Webhook.site for initial experimentation.

Verify your endpoint independently (a quick test with curl or Postman) before involving Gravity Forms. This eliminates variables and makes debugging faster if something goes wrong later.

Creating Your First Webhook Feed

Each webhook in Gravity Forms is configured as a feed attached to a specific form. One form can have multiple webhook feeds, each sending data to a different endpoint or under different conditions.

Step-by-Step Feed Setup

Open the form you want to connect in the Gravity Forms editor.
Navigate to Settings > Webhooks > Add New.
Give the feed a descriptive Name (for example, “Airtable Lead Sync” or “n8n Order Processing”). This label is internal only and never shown to visitors.
Enter the Request URL — the endpoint where data will be sent. This field supports merge tags, so dynamic URLs are possible.
Select the Request Method: GET, POST, PUT, PATCH, or DELETE. POST is the most common choice for form submission data.
Choose the Request Format: JSON or FORM. Most modern APIs expect JSON. Legacy endpoints may require FORM (URL-encoded).
Add any required Request Headers (authentication tokens, custom identifiers).
Configure the Request Body: either send all fields (the entire unformatted entry) or select specific fields and map them to custom parameter names.
Optionally set a Webhook Condition so the feed only fires when certain criteria are met.
Click Save Settings and submit a test entry to verify the connection.

Two important notes from the official documentation: the Content-Type header is automatically set to application/json when you select JSON format with POST or PUT methods, so you do not need to add it manually. Additionally, the Request URL must pass WordPress core validation — custom ports and redirects to URLs that fail validation will abort feed processing.

Authentication: Bearer Tokens, Basic Auth, and Custom Headers

Nearly every external API requires authentication. The Request Headers section of the webhook feed is where you handle it. Here are the three most common patterns.

Bearer Token Authentication

Used by most modern APIs (Airtable, Notion, many SaaS platforms). Add a header with:

Name: Authorization
Value: Bearer your_api_token_here

Replace the token with the value provided by the external service. For static tokens, paste the value directly. For tokens stored in wp-config.php as constants, use the gform_webhooks_request_headers filter to inject them dynamically — never hardcode sensitive credentials in the Gravity Forms UI if multiple team members have form access.

Basic Authentication

Older APIs and some internal tools still use Basic auth. The header format is:

Name: Authorization
Value: Basic base64(username:password)

You need to Base64-encode the username:password string before pasting it into the header value. Online tools or a quick terminal command (echo -n "user:pass" | base64) handle the encoding. Basic auth should only be used over HTTPS connections.

Custom API Key Headers

Some services define their own header names for authentication. Basin, for example, expects a Basin-API-Key header and a Basin-True-Client-IP header for spam filtering. Always consult the target service’s documentation for the exact header names and values required.

Mapping Fields and Building the Request Body

When you select “Select Fields” for the Request Body, you gain granular control over what data is transmitted. Each row in the Field Values section lets you map a form field (or entry meta, or a custom value) to a parameter name that matches what the external API expects.

For example, your form might have a field labeled “Full Name” with ID 1 and the external API expects a parameter called contact_name. In the Field Values section, set the key to contact_name and select the “Full Name” field as the value. The resulting JSON payload would include "contact_name": "Jane Smith" instead of a generic field ID reference.

Merge tags work throughout the body configuration. You can reference {Name (First):1.3} for a first name from a Name field, {:date_created} for the submission timestamp, or {created_by} for the logged-in user’s ID. If you need a deeper introduction to field value references, our guide to Gravity Forms dynamic population covers the merge tag system in detail.

Custom JSON Structures with the gform_webhooks_request_data Filter

The standard UI handles flat key-value pairs well, but many APIs expect nested JSON. If your target endpoint needs a structure like:

{
  "contact": {
    "name": "Jane Smith",
    "email": "[email protected]"
  },
  "source": {
    "form_id": 5,
    "submitted_at": "2026-03-25"
  }
}

You will need the gform_webhooks_request_data PHP filter. This hook receives the default request data and lets you restructure it before it is sent:

add_filter( 'gform_webhooks_request_data', function( $request_data, $feed, $entry, $form ) {
    $request_data['body'] = json_encode( [
        'contact' => [
            'name'  => rgar( $entry, '1' ),
            'email' => rgar( $entry, '2' ),
        ],
        'source' => [
            'form_id'      => $form['id'],
            'submitted_at' => rgar( $entry, 'date_created' ),
        ],
    ] );
    return $request_data;
}, 10, 4 );

Place this code in your theme’s functions.php file or, better, in a site-specific plugin. The rgar() function is a Gravity Forms helper that safely retrieves entry values by field ID.

Real-World Integration Examples

Understanding webhook configuration in the abstract only goes so far. Here are three practical integrations that cover the most common patterns.

Sending Lead Data to n8n

n8n is an open-source automation platform that can replace Zapier for users who want self-hosted control. To connect Gravity Forms to n8n:

In n8n, create a new workflow and add a Webhook trigger node. Copy the Test URL it generates.
In Gravity Forms, create a webhook feed with the n8n test URL as the Request URL. Set the method to POST, format to JSON, and configure your field mappings.
Submit a test form entry. In n8n, click Listen for Test Event to capture the incoming data.
Once confirmed, add downstream nodes in n8n (Google Sheets, Slack notification, CRM update, etc.).
Switch the Gravity Forms webhook URL from the n8n test URL to the Production URL before going live.

The advantage of this approach is that n8n handles all downstream complexity — data transformation, conditional routing, retries — while Gravity Forms simply pushes submission data to a single endpoint.

Direct Integration with Airtable

Airtable’s API accepts direct webhook requests, making it possible to create records without middleware:

In Airtable, open the base and table you want to populate. Go to Automations > Create Automation > When webhook received. Copy the generated webhook URL.
Create a Gravity Forms webhook feed pointing to this URL. Method: POST. Format: JSON.
Add an Authorization header with the value Bearer YOUR_AIRTABLE_PAT (your Airtable Personal Access Token).
Map form fields to the column names Airtable expects.
Submit a test entry and return to Airtable to confirm the record was created.

Pushing Submissions to a Custom REST API

For teams that maintain internal tools or custom applications, webhooks can send form data directly to your own API endpoint. If you are building a custom REST API on WordPress, our REST API authentication guide covers the security fundamentals. The pattern is the same: point the Request URL at your endpoint, authenticate using whatever scheme your API uses, and map fields to your expected parameters. If your API expects nested JSON, use the gform_webhooks_request_data filter to restructure the payload before it ships.

Conditional Webhook Execution

Not every form submission needs to trigger a webhook. The Webhook Condition setting at the bottom of each feed lets you define rules that determine when the webhook fires. For example:

Only send data when a “Lead Type” dropdown equals “Enterprise.”
Skip the webhook if a “Subscribe to Newsletter” checkbox is unchecked.
Fire the webhook only when the total payment amount exceeds a threshold.

Conditions reference form field values, so make sure you are targeting the field’s stored value rather than its display label. This is a common source of confusion: a dropdown might display “Enterprise Plan” to the user but store “enterprise” as the value. The condition must match the stored value.

Debugging, Logging, and Error Handling

When a webhook does not work as expected, systematic debugging saves hours of guesswork.

Enable Gravity Forms Logging

Navigate to Forms > Settings > Logging and toggle it on. After submitting a test form, return to the logging page and select the Webhooks log. This log records every webhook request attempt, including the HTTP status code of the response, the URL called, and any errors encountered. The Gravity Forms logging documentation covers additional configuration options.

Interpret HTTP Status Codes

Status Code	Meaning	Common Fix
`200` or `201`	Success	No action needed.
`400`	Bad Request	Check JSON formatting and required parameters. Validate your payload with a JSON linter.
`401`	Unauthorized	Verify your Authorization header value. Confirm the API token has not expired.
`403`	Forbidden	Token is valid but lacks the required permissions. Check API key scopes.
`404`	Not Found	Double-check the Request URL for typos or outdated endpoints.
`500`	Server Error	The receiving server has an issue. Test the endpoint independently with curl or Postman.
Timeout	No response in time	The external service is slow. Reduce payload size or check server resources on both ends.

Set Up Failure Notifications

Webhooks can fail silently. Without monitoring, you might not discover a broken integration for days or weeks. The gform_webhooks_post_request action hook lets you trigger an alert whenever a request fails:

add_action( 'gform_webhooks_post_request', function( $response, $feed, $entry, $form ) {
    if ( is_wp_error( $response ) ) {
        $error_message = $response->get_error_message();
        wp_mail(
            '[email protected]',
            'Webhook Failed: ' . $feed['meta']['feedName'],
            "Form: {$form['title']}\nEntry ID: {$entry['id']}\nError: {$error_message}"
        );
    }
}, 10, 4 );

This snippet emails you immediately when a webhook returns a WP_Error, including the form name, entry ID, and error message for fast diagnosis.

Use External Testing Tools

Services like Webhook.site and RequestBin let you generate a temporary URL that captures and displays incoming webhook payloads. Point your Gravity Forms webhook at one of these tools during development to inspect exactly what data is being sent, in what format, and with what headers. This eliminates guesswork about whether the problem is on the sending or receiving side.

Security Best Practices

Form submission data often includes personal information, so webhook security deserves deliberate attention. For broader hardening advice beyond webhooks, see our Gravity Forms security guide.

Always use HTTPS endpoints. HTTP transmits data in plaintext, making it visible to anyone monitoring the network.
Store credentials securely. Define API tokens as constants in wp-config.php and reference them in your filter code rather than pasting them into the Gravity Forms UI or committing them to version control.
Limit the data you send. Use “Select Fields” instead of “All Fields” to avoid transmitting sensitive information (payment details, passwords, government IDs) that the external service does not need.
Audit your webhook feeds periodically. External endpoints change, API tokens expire, and services shut down. A quarterly review of active webhook feeds prevents silent integration failures.
Use webhook conditions to filter submissions. If only certain entries should reach an external system, conditional logic prevents unnecessary data transmission.

Webhooks vs. Dedicated Add-Ons vs. Zapier: When to Use Each

Gravity Forms offers multiple integration approaches, and choosing the right one saves both time and money. Our complete add-on comparison chart covers every official add-on if you want to see what dedicated integrations are available before deciding on webhooks.

Approach	Best For	Trade-offs
Dedicated Add-Ons (HubSpot, Mailchimp, Stripe, etc.)	Officially supported services with complex, bidirectional needs	Limited to services Gravity Forms has built add-ons for
Webhooks Add-On	Any service with an HTTP endpoint; custom APIs; full payload control	Requires understanding of HTTP methods, headers, and JSON formatting
Zapier Add-On	Non-technical users who need quick connections to 7,000+ apps	Monthly subscription cost; less control over data structure; external dependency

The Webhooks Add-On sits in the middle: more flexible than dedicated add-ons (which are locked to one service) and more controlled than Zapier (which adds cost and a third-party dependency). If you need direct, no-middleman data transfer with full formatting control, webhooks are the right tool.

Keeping Your Webhook Integrations Healthy

A webhook that works on launch day can quietly break weeks later. Build ongoing reliability into your workflow with these practices:

Test after every WordPress or Gravity Forms update. Core updates can occasionally change how HTTP requests are processed.
Monitor with the failure notification hook. The gform_webhooks_post_request code snippet shown earlier is a low-effort, high-value safeguard.
Keep the Webhooks Add-On updated. Version 1.7 (2025) included security enhancements and improved compatibility with Gravity Forms 2.9.4+. Running outdated versions exposes you to patched vulnerabilities.
Document your webhook feeds. Record which forms connect to which endpoints, what authentication is used, and who to contact at the external service. This documentation pays for itself the first time something breaks at 2 AM.
Use a staging environment for changes. Test new webhook configurations on a staging site before deploying to production. This prevents accidental data transmission to live systems during development.

Conclusion

The Gravity Forms Webhooks Add-On transforms your forms from data collectors into active integration endpoints. Any service that accepts HTTP requests can receive your form data in real time, formatted exactly the way the receiving API expects it.

Start with a simple use case: pick one form and one external service, configure the feed using the steps in this guide, and verify the connection with a test submission. Once the fundamentals click, you can expand to multi-feed configurations, conditional execution, custom JSON structures via PHP filters, and failure monitoring that ensures no submission slips through unnoticed.

For sites managing many forms and complex data flows, combining webhooks with entry management tools and form analytics gives you visibility into what is being submitted, where it is going, and whether the pipeline is performing as expected.