Create Webhook Integration

Create a new webhook integration for a form. Requires manage-integrations ability.

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.

Show data properties

webhook_url · string · required

The URL where form submissions will be sent. Must be a valid HTTP/HTTPS URL.

webhook_secret · 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.

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

logic · object

Optional conditional logic to trigger the webhook only when specific conditions are met.

cURL

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.

Success

{
  "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).

Error

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

Show child attributes

status · enum<string> · default: active

The initial status of the webhook

Available options:

active,

inactive

Response

200

application/json

Webhook created successfully

message · string

Example:

"Form Integration was created."

form_integration · object

Show child attributes