Webhooks

Overview

Webhooks let you send form submission data to any external URL the moment a form is submitted. Formcierge fires a POST request with a JSON body containing the submission data.

Setting Up a Webhook

1. Open your form in the builder and go to Settings → Notifications → Webhooks.
2. Click Add Webhook.
3. Enter the endpoint URL.
4. Optionally set a secret key for HMAC signature verification.
5. Save the form.

Payload Format

The JSON body sent to your endpoint:

{
  "form_id": 42,
  "entry_id": 1337,
  "submitted_at": "2025-03-15T14:22:00Z",
  "fields": {
    "full_name": "Jane Smith",
    "email": "jane@example.com",
    "message": "Hello from the form"
  }
}

Signature Verification

When a secret is set, Formcierge adds an X-Formcierge-Signature header to every request. Verify it server-side:

$payload   = file_get_contents( 'php://input' );
$secret    = 'your_webhook_secret';
$signature = hash_hmac( 'sha256', $payload, $secret );

if ( ! hash_equals( $signature, $_SERVER['HTTP_X_FORMCIERGE_SIGNATURE'] ?? '' ) ) {
    http_response_code( 401 );
    exit;
}

Retries

If your endpoint returns a non-2xx status code, Formcierge retries the webhook up to 3 times with exponential backoff (5 s, 25 s, 125 s). Failed deliveries are logged in Formcierge → Settings → Webhooks → Delivery Log.

Triggering Webhooks via PHP

You can also fire webhooks programmatically using the formcierge_trigger_webhook action:

do_action( 'formcierge_trigger_webhook', $form_id, $entry_id, $payload );