Integrations

Create Webhook Integration

Add a new webhook integration to send form submissions to an external endpoint.

POST

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

formnumber required

The ID of the form to which the webhook will be added.

integration_idstring required

Must be set to "webhook" for webhook integrations.

statusstring required

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

dataobject required

Configuration object containing webhook details.

data properties

webhook_urlstring required

The 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

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_headersobject

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:

json

{
    "X-API-Key": "your-api-key",
    "X-Custom-ID": "custom-value"
}

logicobject

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

#Response

200 OK – Webhook created successfully.

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 or non-public webhook URL, webhook_secret too short, blocked header).

#Security

If you provide a webhook_secret when creating the webhook, SharaForms will sign each webhook request with an HMAC-SHA256 signature. This allows you to verify that the webhook came from SharaForms and hasn't been tampered with.

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.

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)
JSON body metadata: The payload includes form_id and submission_id so you can correlate webhook deliveries with SharaForms API submission management endpoints

#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.

Warning

Do not commit webhook secrets to version control. Use environment variables or secure vaults to manage them.