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 webhook URL, webhook_secret too short, blocked header). 
{
  "message": "The given data was invalid.",
  "errors": {
    "data.webhook_url": ["The webhook url must be a valid URL."],
    "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. 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)

​
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