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"
      }
    }
  }
}

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

number

required

The ID of the form to which the webhook will be added.

string

required

Use "webhook" for a generic webhook integration or "make" for the official OpnForm app on Make. Both values are registered integration handlers exposed by this endpoint.

string

required

The initial status of the webhook. Allowed values: "active", "inactive".

object

required

Configuration object containing webhook details.

Show data properties

string

required

The URL where form submissions will be sent. Must be a valid HTTPS URL that resolves only to public IP addresses. Private, loopback, link-local, shared (CGNAT), protocol-assignment, benchmark, and cloud metadata addresses are rejected. IPv4-mapped IPv6, NAT64 (64:ff9b::/96 and 64:ff9b:1::/48), and 6to4 destinations are also rejected, including when they embed a public IPv4 address.

string

Optional signing secret for HMAC-SHA256 validation. When provided, webhook requests will include an X-Webhook-Signature header. Must be at least 12 characters. Recommended for security. Should be a random, cryptographically secure string.

object

Optional custom HTTP headers to send with each webhook request. Provided as key-value pairs where both keys and values are strings. Maximum 10 headers allowed, each value max 255 characters.Blocked headers (cannot be customized): Authorization, X-Webhook-Signature, Content-Type, Host, Cookie, X-CSRF-Token, Content-Length, and others reserved for security.Example:

{
    "X-API-Key": "your-api-key",
    "X-Custom-ID": "custom-value"
}

string

Optional Make scenario URL. This property is accepted by the "make" integration and is ignored by generic webhook integrations.

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"
      }
    }
  }'

For the official OpnForm app on Make, the attach request uses the same endpoint with the provider-specific integration identifier:

curl -X POST 'https://api.opnform.com/open/forms/123/integrations' \
  -H 'Authorization: Bearer YOUR_PAT' \
  -H 'Content-Type: application/json' \
  -d '{
    "integration_id": "make",
    "status": "active",
    "logic": null,
    "data": {
      "webhook_url": "https://hook.eu1.make.com/example"
    }
  }'

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.

Make payload

The "make" handler sends a provider-specific payload matching the output interface of the OpnForm Make app:

{
  "form_id": 123,
  "form_title": "Contact Form",
  "form_slug": "contact-form",
  "submission_id": 456,
  "edit_link": "https://opnform.com/forms/contact-form?submission_id=example",
  "data": {
    "field-id": {
      "value": "Jane Doe",
      "name": "Name",
      "type": "text"
    }
  }
}

edit_link is present only when editable submissions are enabled. Unlike the generic webhook payload, the Make payload omits the deprecated submission and message properties.

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

Use "webhook" for a generic webhook or "make" for the official OpnForm app on Make

Available options:

webhook,

make

data

object

required

Show child attributes

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

Show child attributes

Overview

Workspaces

Forms

Submissions

Integrations

Workspace Users

Zapier

Create Webhook Integration

Create Webhook Integration

Authentication & Scope

Request

Response

Security

Blocked Headers

Make payload

Authorizations

Path Parameters

Body

Response

​Create Webhook Integration

​Authentication & Scope

​Request

​Response

​Security

​Blocked Headers

​Make payload

Authorizations

Path Parameters

Body

Response

Create Webhook Integration

Authentication & Scope

Request

Response

Security

Blocked Headers

Make payload