Skip to main content

​
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!"
  }
}
FieldDescription
form_idThe numeric ID of the form
form_nameThe form’s title
submission_idUnique session ID for this submission
submitted_atISO 8601 timestamp
dataKey-value pairs mapping question text to the respondent’s answer
The request includes these headers:
HeaderValue
Content-Typeapplication/json
User-AgentGeniusFormsAI-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

RuleDetail
URL formatMust be a valid HTTP or HTTPS URL
URL lengthMaximum 2000 characters
EnablingwebhookEnabled: true requires a webhookUrl to be set (on the form or in the same request)
Clearing URLSetting webhookUrl to null or "" automatically sets webhookEnabled to false