Update Webhook Integration

Update an existing webhook integration. Requires manage-integrations ability.

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.

Show data properties

webhook_url · string

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

webhook_secret · string

Update the signing secret for HMAC-SHA256 validation. Must be at least 12 characters. Provide a new value to rotate the secret.

webhook_headers · object

Update custom HTTP headers. Replaces all existing headers with the provided ones. Maximum 10 headers allowed. See blocked headers list below for restricted header names.

logic · object

Update the conditional logic for webhook triggering.

cURL

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.

Success

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

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

Show child attributes

status · enum<string>

The status of the webhook

Available options:

active,

inactive

Response

200

application/json

Webhook updated successfully

message · string

Example:

"Form Integration was updated."

form_integration · object

Show child attributes