Setting Up Webhooks

What Are Webhooks?

Webhooks allow WittyForm to send form submission data to any external URL in real time. When someone submits your form, WittyForm makes an HTTP POST request to your specified endpoint with the submission data as a JSON payload. This lets you connect WittyForm to any service, app, or custom backend that can receive HTTP requests.

Common use cases for webhooks include:

• Sending data to a custom backend or database.
• Triggering workflows in automation tools.
• Updating a CRM or help desk system.
• Logging submissions to a custom analytics pipeline.

Adding a Webhook URL

1. Open your form in the editor and go to the Integrations tab.
2. Find Webhooks and click Add Webhook.
3. Enter your webhook URL. This must be a publicly accessible HTTPS endpoint (e.g., https://your-server.com/api/form-submissions).
4. Give the webhook a name for your reference (e.g., "CRM Sync" or "Backend API").
5. Click Save.

You can add multiple webhooks to a single form if you need to send data to several endpoints.

JSON Payload Format

Each webhook delivery sends a JSON payload with the same structure as this example:

{
  "event": "form.submitted",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "formId": "form-uuid",
  "data": {
    "formId": "form-uuid",
    "responseId": "response-uuid",
    "answers": {
      "field-id": "Jane Smith",
      "another-field-id": "[email protected]"
    },
    "displayAnswers": {
      "field-id": "Jane Smith"
    },
    "submittedAt": "2026-01-15T10:30:00.000Z",
    "form": {
      "id": "form-uuid",
      "title": "Contact Form"
    }
  }
}

Field answers are keyed by field ID. Use displayAnswers when you need human-readable choice labels.

n8n, Bitflows, and Cloudflare

1. In n8n, copy the production URL beginning with /webhook/, not the temporary /webhook-test/ URL.
2. Activate the n8n workflow before submitting the WittyForm. A production webhook is not registered while the workflow is inactive.
3. Use Send Test from the WittyForm webhook panel to send a safe sample containing your form field IDs, or submit the form once for a real delivery.
4. If the destination is behind Cloudflare and the delivery log shows HTTP 403 or a challenge page, open the webhook edit screen and copy its Delivery Token. Configure the destination Cloudflare WAF/rate-limit rule to allow or skip rate limiting when X-WittyForm-Webhook-Token exactly matches that token. WittyForm cannot change a third-party Cloudflare account automatically.

Testing with webhook.site

Before connecting your production endpoint, test your webhook setup using a free tool like webhook.site:

1. Go to https://webhook.site and copy your unique URL.
2. Paste it as your webhook URL in the WittyForm integration settings.
3. Submit a test response to your form.
4. Check webhook.site to see the exact payload that was delivered. Verify the data structure matches what your endpoint expects.
5. Once confirmed, replace the test URL with your actual endpoint.

Headers and Authentication

If your endpoint requires authentication or custom headers, you can configure them in the webhook settings:

• Custom Headers: Add any key-value pair as an HTTP header. Click Add Header and enter the header name and value. Common examples:
  • Authorization: Bearer your-api-token
  • X-API-Key: your-api-key
• Signing Secret: WittyForm can sign each webhook payload with an HMAC signature. Enable this and set a secret key. The signature is sent in the X-Webhook-Signature header, allowing your endpoint to verify the request came from WittyForm.

Retry Logic

If your endpoint returns an error (HTTP status 4xx or 5xx) or is unreachable, WittyForm automatically retries the delivery:

• Retry 1: about 1 second after the initial failure.
• Retry 2: about 5 seconds later.
• Retry 3: about 30 seconds later.
• Retry 4: about 5 minutes later.
• Retry 5: about 1 hour later, subject to your configured retry limit.

If all retries fail, the webhook delivery is marked as "Failed" in your dashboard. The submission data is still saved in WittyForm and you can manually re-trigger the webhook.

Debugging Failed Deliveries

WittyForm logs every webhook delivery attempt. To view the logs:

1. Go to Integrations > Webhooks > Delivery Log.
2. Each entry shows:
   • Timestamp: When the delivery was attempted.
   • Status: Success (2xx) or the specific error code returned.
   • Response Body: The response from your endpoint (helpful for debugging).
   • Request Payload: The exact JSON that was sent.
3. Click Retry on any failed delivery to re-send the webhook manually.

Best Practices

• Return a 200 status quickly: Your endpoint should respond with a 200 status as soon as it receives the data. Process the data asynchronously if it takes time.
• Handle duplicate deliveries: Use the submission_id to detect and ignore duplicate deliveries caused by retries.
• Validate the signature: If you enabled signing, always verify the HMAC signature before processing the payload to prevent unauthorized requests.
• Use HTTPS only: Webhook URLs must use HTTPS to ensure data is encrypted in transit.