Skip to main content
POST
/
open
/
forms
/
{form}
/
integrations
curl -X POST 'https://api.opnform.com/open/forms/123/integrations' \
  -H 'Authorization: Bearer YOUR_PAT' \
  -H 'Content-Type: application/json' \
  -d '{
    "integration_id": "webhook",
    "status": "active",
    "data": {
      "webhook_url": "https://example.com/opnform-hook",
      "webhook_secret": "whsec_1234567890abcdefghijklmnop",
      "webhook_headers": {
        "X-API-Key": "my-api-key",
        "X-Custom-Header": "custom-value"
      }
    }
  }'

{
  "message": "Form Integration was created.",
  "form_integration": {
    "id": 42,
    "form_id": 123,
    "integration_id": "webhook",
    "status": "active",
    "data": {
      "webhook_url": "https://example.com/opnform-hook",
      "webhook_secret": "whsec_1234567890abcdefghijklmnop",
      "webhook_headers": {
        "X-API-Key": "my-api-key",
        "X-Custom-Header": "custom-value"
      }
    }
  }
}

​
Create Webhook Integration

Add a new webhook integration to send form submissions to an external endpoint.

​
Authentication & Scope

This endpoint requires a Personal Access Token with the manage-integrations ability.

​
Request

​
form
number
required
The ID of the form to which the webhook will be added.
​
integration_id
string
required
Must be set to "webhook" for webhook integrations.
​
status
string
required
The initial status of the webhook. Allowed values: "active", "inactive".
​
data
object
required
Configuration object containing webhook details.
​
logic
object
Optional conditional logic to trigger the webhook only when specific conditions are met.
curl -X POST 'https://api.opnform.com/open/forms/123/integrations' \
  -H 'Authorization: Bearer YOUR_PAT' \
  -H 'Content-Type: application/json' \
  -d '{
    "integration_id": "webhook",
    "status": "active",
    "data": {
      "webhook_url": "https://example.com/opnform-hook",
      "webhook_secret": "whsec_1234567890abcdefghijklmnop",
      "webhook_headers": {
        "X-API-Key": "my-api-key",
        "X-Custom-Header": "custom-value"
      }
    }
  }'

​
Response

200 OK – Webhook created successfully. 
{
  "message": "Form Integration was created.",
  "form_integration": {
    "id": 42,
    "form_id": 123,
    "integration_id": "webhook",
    "status": "active",
    "data": {
      "webhook_url": "https://example.com/opnform-hook",
      "webhook_secret": "whsec_1234567890abcdefghijklmnop",
      "webhook_headers": {
        "X-API-Key": "my-api-key",
        "X-Custom-Header": "custom-value"
      }
    }
  }
}
403 Forbidden – The token does not have manage-integrations ability or insufficient form permissions. 404 Not Found – Form not found. 422 Unprocessable Entity – Validation error (e.g., invalid or non-public webhook URL, webhook_secret too short, blocked header). 
{
  "message": "The given data was invalid.",
  "errors": {
    "data.webhook_url": ["The webhook URL must use HTTPS."],
    "data.webhook_secret": ["The webhook secret must be at least 12 characters."],
    "data.webhook_headers": ["The 'Authorization' header cannot be customized for security reasons."]
  }
}

​
Security

If you provide a webhook_secret when creating the webhook, OpnForm will sign each webhook request with an HMAC-SHA256 signature. This allows you to verify that the webhook came from OpnForm and hasn’t been tampered with. Webhook URLs are validated when they are saved and again before each delivery. OpnForm does not follow webhook redirects, and private network destinations are blocked unless the instance operator explicitly enables private webhook URLs for a self-hosted deployment. Each webhook request will include:
  • X-Webhook-Signature header: Contains the signature in format sha256=HEXADECIMAL_VALUE
  • Custom headers: Any headers you specified in webhook_headers (except blocked headers)
  • JSON body metadata: The payload includes form_id and submission_id so you can correlate webhook deliveries with OpnForm API submission management endpoints

​
Blocked Headers

For security reasons, the following headers cannot be customized:
  • Authorization
  • X-Webhook-Signature
  • Content-Type
  • Content-Length
  • Host
  • Cookie
  • X-CSRF-Token
  • X-Forwarded-For
  • X-Forwarded-Proto
  • X-Real-IP
See Validating Webhook Signatures for implementation examples.
Do not commit webhook secrets to version control. Use environment variables or secure vaults to manage them.

Authorizations

​
Authorization
string
header
required

Personal Access Token

Path Parameters

​
form
number
required

The ID of the form.

Body

application/json
​
integration_id
enum<string>
required

Must be "webhook"

Available options:
webhook
​
data
object
required
​
status
enum<string>
default:active

The initial status of the webhook

Available options:
active,
inactive

Response

Webhook created successfully

​
message
string
Example:

"Form Integration was created."

​
form_integration
object