Integrations

Update Webhook Integration

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

PUT

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

formnumber required

The ID of the form containing the webhook.

integrationidnumber required

The ID of the webhook integration to update.

integration_idstring required

Must be set to "webhook".

statusstring

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

dataobject required

Configuration object containing webhook details. All fields are optional.

data properties

webhook_urlstring

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.

webhook_secretstring

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

webhook_headersobject

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.

logicobject

Update the conditional logic for webhook triggering.

#Response

200 OK – Webhook updated successfully.

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.

#Security

Webhook URLs are validated when they are saved and again before each delivery. SharaForms 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 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.