Skip to main content

Webhooks

LocalForm can POST every submission as JSON to an external endpoint - for payment flows, CRMs, automation tools, or custom backends.

Configuration​

  • Per form: set Webhook URL in the form editor's General panel.
  • Default: set a fallback URL under LocalForm → Settings → Webhooks, used by forms without their own URL.
  • Webhook-only mode: uncheck Save submissions in WordPress (also in the General panel) to skip local storage and only deliver to the webhook.

The General panel, with Webhook URL, Redirect URL, and Save submissions in WordPress

Payload​

{
	"form_id": 12,
	"submission_id": 345,
	"timestamp": "2026-07-23T10:00:00+00:00",
	"event_date": "2026-09-01",
	"payment_price": 25.0,
	"fields": { "name": "…", "email": "…" },
	"custom_fields": { "any": "key-value pairs from the form's Custom Fields panel" }
}

submission_id is null in webhook-only mode. Custom fields are key-value pairs that ride along in every payload without being shown on the form itself:

The Custom Fields panel

A form with multiple event dates (Pro) also carries an event_dates array holding the full schedule in machine-readable form.

LocalForm Pro adds Global Webhook Fields (LocalForm → Settings → Webhooks → Fields) - key-value pairs merged into every form's payload. A per-form custom field overrides a global one that shares the same key.

The Global Webhook Fields screen

Signing​

When a secret key is configured (LocalForm → Settings → Webhooks → Webhook Secret Key), requests carry an HMAC-SHA256 signature of the JSON body so the receiver can verify authenticity.

The Webhooks configuration screen, with the default URL and secret key

Delivery and retries​

Deliveries are queued (via WP-Cron) and retried up to 3 times with exponential backoff (0s / 1 min / 5 min). Every attempt is recorded under LocalForm → Settings → Webhooks → Logs (payload, response code, response body), with 30-day retention.

The Webhook Logs screen, showing two completed deliveries

Redirecting after submission​

Two ways to send visitors elsewhere after a successful submission:

  • Redirect URL on the form itself (General panel) always redirects there, regardless of the webhook.
  • If the receiving endpoint responds with an X-LocalForm-Redirect header (or a redirect_url key in its JSON response - both names configurable under Settings → Webhooks → Redirect), the visitor is redirected there instead - useful for payment checkouts. A form-level Redirect URL takes priority over one returned by the webhook.

The frontend polls the delivery status briefly and falls back to the normal success message.