Skip to main content
PUT
/
open
/
forms
/
{form}
/
integrations
/
{integrationid}
curl -X PUT 'https://api.opnform.com/open/forms/123/integrations/42' \
  -H 'Authorization: Bearer YOUR_PAT' \
  -H 'Content-Type: application/json' \
  -d '{
    "integration_id": "webhook",
    "status": "active",
    "data": {
      "webhook_url": "https://new-endpoint.com/opnform-hook",
      "webhook_secret": "whsec_newsecret123456789abcdef",
      "webhook_headers": {
        "X-API-Key": "new-api-key",
        "X-Custom-ID": "updated-value"
      }
    }
  }'

{
  "message": "Form Integration was updated.",
  "form_integration": {
    "id": 42,
    "form_id": 123,
    "integration_id": "webhook",
    "status": "active",
    "data": {
      "webhook_url": "https://new-endpoint.com/opnform-hook",
      "webhook_secret": "whsec_newsecret123456789abcdef",
      "webhook_headers": {
        "X-API-Key": "new-api-key",
        "X-Custom-ID": "updated-value"
      }
    }
  }
}

​
Update Webhook Integration

Modify an existing webhook integration’s URL, secret, headers, or status.

​
Authentication & Scope

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

​
Request

​
form
number
required
The ID of the form containing the webhook.
​
integrationid
number
required
The ID of the webhook integration to update.
​
integration_id
string
required
Must be set to "webhook".
​
status
string
The status of the webhook. Allowed values: "active", "inactive".
​
data
object
required
Configuration object containing webhook details. All fields are optional.
​
logic
object
Update the conditional logic for webhook triggering.
curl -X PUT 'https://api.opnform.com/open/forms/123/integrations/42' \
  -H 'Authorization: Bearer YOUR_PAT' \
  -H 'Content-Type: application/json' \
  -d '{
    "integration_id": "webhook",
    "status": "active",
    "data": {
      "webhook_url": "https://new-endpoint.com/opnform-hook",
      "webhook_secret": "whsec_newsecret123456789abcdef",
      "webhook_headers": {
        "X-API-Key": "new-api-key",
        "X-Custom-ID": "updated-value"
      }
    }
  }'

​
Response

200 OK – Webhook updated successfully. 
{
  "message": "Form Integration was updated.",
  "form_integration": {
    "id": 42,
    "form_id": 123,
    "integration_id": "webhook",
    "status": "active",
    "data": {
      "webhook_url": "https://new-endpoint.com/opnform-hook",
      "webhook_secret": "whsec_newsecret123456789abcdef",
      "webhook_headers": {
        "X-API-Key": "new-api-key",
        "X-Custom-ID": "updated-value"
      }
    }
  }
}
403 Forbidden – The token does not have manage-integrations ability or insufficient form permissions. 404 Not Found – Form or integration not found. 422 Unprocessable Entity – Validation error. 
{
  "message": "The given data was invalid.",
  "errors": {
    "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

​
Secret Rotation

When updating the webhook_secret, the new secret will be used for all future webhook requests. Existing webhook attempts with the old secret will fail validation on the receiver’s end. If you need to rotate your secret, consider implementing a grace period on your receiving endpoint to accept both old and new secrets during the transition.

​
Blocked Headers

For security reasons, the following headers cannot be customized in webhook_headers:
  • Authorization
  • X-Webhook-Signature
  • Content-Type
  • Content-Length
  • Host
  • Cookie
  • X-CSRF-Token
  • X-Forwarded-For
  • X-Forwarded-Proto
  • X-Real-IP
For signature validation implementation examples, see Validating Webhook Signatures.

Authorizations

​
Authorization
string
header
required

Personal Access Token

Path Parameters

​
form
number
required

The ID of the form.

​
integrationid
number
required

The ID of the integration.

Body

application/json
​
integration_id
enum<string>
required

Must be "webhook"

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

The status of the webhook

Available options:
active,
inactive

Response

Webhook updated successfully

​
message
string
Example:

"Form Integration was updated."

​
form_integration
object