Webhooks

Overview

Webhooks let you receive an HTTP POST request to your server whenever a form submission is completed. This enables real-time integrations with your backend, CRM, notification systems, or any external service. A webhook fires when all required questions on a form have been answered.

Configuring a Webhook

Use the Update Form endpoint to set a webhook URL and enable delivery:

curl -X PATCH https://geniusforms.ai/api/v1/forms/208 \
  -H "X-API-Key: gf_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://example.com/webhooks/geniusforms",
    "webhookEnabled": true
  }'

The response includes the updated webhook configuration:

{
  "id": 208,
  "title": "Customer Feedback",
  "webhook": {
    "enabled": true,
    "url": "https://example.com/webhooks/geniusforms"
  }
}

Disabling a Webhook

Set webhookEnabled to false to stop deliveries without removing the URL:

curl -X PATCH https://geniusforms.ai/api/v1/forms/208 \
  -H "X-API-Key: gf_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "webhookEnabled": false }'

To clear the URL entirely, set webhookUrl to null. This automatically disables the webhook:

curl -X PATCH https://geniusforms.ai/api/v1/forms/208 \
  -H "X-API-Key: gf_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "webhookUrl": null }'

Payload Format

When a form submission is completed, GeniusForms sends a POST request with a JSON body:

{
  "form_id": 208,
  "form_name": "Customer Feedback",
  "submission_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "submitted_at": "2026-02-07T14:30:00.000Z",
  "data": {
    "Your name": "Jane Smith",
    "Your email": "jane@example.com",
    "How satisfied are you?": "5",
    "Any additional feedback?": "Great product, keep it up!"
  }
}

Field	Description
`form_id`	The numeric ID of the form
`form_name`	The form’s title
`submission_id`	Unique session ID for this submission
`submitted_at`	ISO 8601 timestamp
`data`	Key-value pairs mapping question text to the respondent’s answer

The request includes these headers:

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`GeniusFormsAI-Webhook/1.0`

Testing Your Webhook

Before going live, verify your endpoint works with the Test Webhook endpoint:

curl -X POST https://geniusforms.ai/api/v1/forms/208/webhook/test \
  -H "X-API-Key: gf_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/webhooks/geniusforms" }'

This sends a sample payload to the URL and returns the result:

{
  "success": true,
  "statusCode": 200,
  "error": null
}

If no url is provided in the request body, it tests the form’s currently configured webhook URL.

Checking Delivery Logs

Use the Get Webhook Logs endpoint to review delivery history:

curl https://geniusforms.ai/api/v1/forms/208/webhook/logs?limit=10 \
  -H "X-API-Key: gf_live_your_key_here"

{
  "logs": [
    {
      "id": 42,
      "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "webhookUrl": "https://example.com/webhooks/geniusforms",
      "status": "success",
      "responseCode": 200,
      "errorMessage": null,
      "createdAt": "2026-02-07T14:30:01.000Z"
    }
  ],
  "total": 1,
  "hasMore": false,
  "limit": 10,
  "offset": 0
}

Checking Webhook Status

Get a quick summary of the current configuration and the last delivery attempt with the Get Webhook Status endpoint:

curl https://geniusforms.ai/api/v1/forms/208/webhook/status \
  -H "X-API-Key: gf_live_your_key_here"

{
  "enabled": true,
  "url": "https://example.com/webhooks/geniusforms",
  "lastDelivery": {
    "status": "success",
    "responseCode": 200,
    "error": null,
    "attemptedAt": "2026-02-07T14:30:01.000Z"
  }
}

Security Notes

HTTPS recommended - Use HTTPS URLs for webhook endpoints to protect payload data in transit.
Localhost blocked in production - localhost, 127.0.0.1, and private IP ranges (192.168.*, 10.*, 172.*) are blocked in production to prevent SSRF attacks.
10-second timeout - Webhook requests time out after 10 seconds. Return a 2xx response quickly and process the data asynchronously if needed.
Non-blocking - Webhook failures never prevent form submissions from being saved. Failed deliveries are logged for debugging.
No retries - Failed webhook deliveries are not automatically retried. Check the delivery logs to identify and resolve issues.

Validation Rules

Rule	Detail
URL format	Must be a valid HTTP or HTTPS URL
URL length	Maximum 2000 characters
Enabling	`webhookEnabled: true` requires a `webhookUrl` to be set (on the form or in the same request)
Clearing URL	Setting `webhookUrl` to `null` or `""` automatically sets `webhookEnabled` to `false`

Getting Started

Guides

Overview

Configuring a Webhook

Disabling a Webhook

Payload Format

Testing Your Webhook

Checking Delivery Logs

Checking Webhook Status

Security Notes

Validation Rules

​Overview

​Configuring a Webhook

​Disabling a Webhook

​Payload Format

​Testing Your Webhook

​Checking Delivery Logs

​Checking Webhook Status

​Security Notes

​Validation Rules

Overview

Configuring a Webhook

Disabling a Webhook

Payload Format

Testing Your Webhook

Checking Delivery Logs

Checking Webhook Status

Security Notes

Validation Rules