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"
}
}
}
}
Integrations
Update Webhook Integration
Update an existing webhook integration. Requires manage-integrations ability.
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 themanage-integrations ability.
Request
number
required
The ID of the form containing the webhook.
number
required
The ID of the webhook integration to update.
string
required
Must be set to
"webhook".string
The status of the webhook. Allowed values:
"active", "inactive".object
required
Configuration object containing webhook details. All fields are optional.
Show data properties
Show data properties
string
The updated URL where form submissions will be sent. Must be a valid HTTPS URL that resolves only to public IP addresses. Private, loopback, link-local, and cloud metadata addresses are rejected.
string
Update the signing secret for HMAC-SHA256 validation. Must be at least 12
characters. Provide a new value to rotate the secret.
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.
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_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
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.Secret Rotation
When updating thewebhook_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 inwebhook_headers:
AuthorizationX-Webhook-SignatureContent-TypeContent-LengthHostCookieX-CSRF-TokenX-Forwarded-ForX-Forwarded-ProtoX-Real-IP
Authorizations
Personal Access Token
Path Parameters
The ID of the form.
The ID of the integration.
Body
application/json
Was this page helpful?