Webhook Action

Send submission data to an external HTTP endpoint using the PRO Webhook automation action.

PRO Last reviewed

The Webhook action sends submission data to an external HTTP endpoint while an automation runs. Use it to pass a new submission to a CRM, an internal API, or another automation service without writing code.

Automations are available in Elzo Forms PRO.

Before you begin

  • The receiving endpoint must be reachable over public HTTP or HTTPS. Local addresses such as localhost and private network addresses are blocked.
  • You need an automation to add the action to. See Create Your First Automation.
  • If the endpoint requires authentication, have its token or API key ready. It is supplied through a request header.

Add a Webhook action

  1. Open the form you want to edit, or go to Forms → Settings → Automations for a Global Automation.
  2. Open the automation, then click Add action.
  3. Select Webhook from the action library. It is listed under the HTTP category.
  4. Enter the Webhook URL.
  5. Set Method and Payload mode. The defaults are POST and All fields.
  6. Add any Headers the endpoint requires.
  7. Save the form, or click Save Automations on the settings screen.

Webhook settings

Setting Description
Webhook URL Required. The destination address. Must start with http:// or https:// and use port 80 or 443.
Method POST (default), GET, PUT, or PATCH.
Payload mode All fields (default) sends every submitted field. Custom mapping sends only the values you list.
Success status from Lowest HTTP status code treated as success. Default 200.
Success status through Highest HTTP status code treated as success. Default 299.
Headers Optional. One Name: Value pair per line.
Mapping Shown only in Custom mapping mode. One target_key: field_id pair per line.

What Elzo Forms sends

In All fields mode the payload contains every submitted field, keyed by its Field Key. You can see and change a field’s key on the Admin tab of the field settings.

In Custom mapping mode the payload contains only the keys you list. Each line uses the format target_key: field_id. When the right-hand value matches a field ID in the submission, that field’s value is sent. Any other value is sent as written, so you can also pass fixed values and workflow references.

Elzo Forms adds these keys to the payload in both modes:

  • elzo_forms_form_id — the ID of the submitted form;
  • elzo_forms_form_name — the form title;
  • elzo_forms_form_slug — the form slug, when the form has one.

For POST, PUT, and PATCH, the payload is sent as a JSON request body. Elzo Forms sets Content-Type: application/json unless you supply your own Content-Type header.

For GET, there is no request body. The payload is appended to the URL as query parameters instead, and any value that is an array is JSON-encoded into a single parameter.

Example payload

{
  "full_name": "Jane Doe",
  "email": "jane@example.com",
  "customer_type": "Business",
  "elzo_forms_form_id": 42,
  "elzo_forms_form_name": "Contact Form",
  "elzo_forms_form_slug": "contact-form"
}

Using submitted values inside settings

The Webhook URL, Headers, and Mapping values accept workflow data references written as {{ path }}. Click Insert data next to a setting to browse the available paths instead of typing them.

Common paths include:

  • {{ fields.by_key.email }} — a submitted value, by Field Key;
  • {{ form.id }} and {{ form.title }} — form details;
  • {{ submission.id }} — the stored submission;
  • {{ variables.my_key }} — a value set earlier by a Set variable action.

When the whole setting is a single reference, the original value type is preserved. When a reference is mixed with other text, the result is a string.

Authentication

There is no separate authentication setting. Send credentials as a request header:

Authorization: Bearer YOUR_TOKEN
X-Api-Key: YOUR_KEY

A few headers are managed by Elzo Forms and cannot be set here: Host, Content-Length, Transfer-Encoding, Connection, Proxy-Authorization, Proxy-Connection, Upgrade, Trailer, TE, and Expect. Configuring one of them makes the action fail.

Header values are stored with the form or in site settings. Treat any site user who can edit forms as able to read them.

How success and failure are decided

The request succeeds when the endpoint replies with a status code inside the configured success range. Anything else is a failure, including a response that never arrives.

A successful action makes two values available to later actions in the same automation, provided you gave the action a Result key on its Admin tab:

  • actions.YOUR_KEY.outputs.status_code
  • actions.YOUR_KEY.outputs.method

The response body is not stored and cannot be read by later actions. If you need data back from the external service, the service must act on the request itself.

When the action fails, the On error setting on its Logic tab decides what happens next: Stop this automation (default), Continue to next action, or Stop all automations.

Note: a failed webhook is not retried. The request is attempted once per matching automation run.

Test a webhook before relying on it

The automation editor can run a webhook against real submission data without waiting for a live visitor.

  1. Submit the form once so there is a submission to test with.
  2. Open the automation and click Test.
  3. Select the form and the submission to use.
  4. Enable Send real webhook requests.
  5. Click Run test.

With that option enabled, every Webhook action the test reaches contacts its real endpoint. Email, cookie, and content actions stay simulated. With the option off, the webhook is validated but no HTTP request is made.

Warning: a real test request creates real records in the receiving service. Point the test at a staging endpoint when the production system cannot accept duplicates.

Limits applied to every request

Webhook requests run inside the automation runtime, which applies fixed safety limits:

Limit Default
Request timeout 10 seconds
HTTP requests per submission 10
Request body size 512 KB
Response size read 1 MB
Redirects followed 3, same-origin only
Headers per request 50

TLS certificates are always verified, and requests to loopback and private network addresses are refused. A developer can adjust some of these limits; see Webhook Integrations for Developers.

Troubleshooting

The webhook never reaches the endpoint

Check: open Forms → Settings → Automations → Health & History and find the run. A Webhook request failed code means the request left WordPress but the endpoint did not answer in time. An Unsafe webhook URL code means the address was rejected before any request was made, usually because it resolves to a local or private address or uses a port other than 80 or 443.

Expected behavior: a completed request records a run with a status code inside the success range.

The endpoint receives the data but the action is marked failed

Check: the recorded diagnostic will be Webhook returned an unexpected status. Compare the status the endpoint returns with Success status from and Success status through. Services that reply 201 or 202 already fall inside the default range; a service that replies 302 or 422 does not.

Expected behavior: the action succeeds when the response status is inside the configured range.

Fields are missing from the payload

Check: in All fields mode, confirm the field has a Field Key on its Admin tab. In Custom mapping mode, confirm each mapping line points at a real field ID; an unmatched value is forwarded as literal text rather than as the field’s value.

Expected behavior: every submitted field appears under its Field Key, alongside the three elzo_forms_* keys.

Only the first few webhooks run

Check: a single submission may make at most 10 HTTP requests across all of its automations. Count the Webhook actions that match on one submission, including those in Global Automations.

Expected behavior: once the limit is reached, further requests fail with an HTTP limit diagnostic and the rest of the workflow continues according to each action’s On error setting.

Next steps

 
Contact us