FormIt Webhook

A MODX FormIt hook that sends form submission data to any external URL via HTTP.

Features

• Send form data via GET, POST, PUT, PATCH, or DELETE
• Three data formats: URL-encoded, multipart form-data, JSON
• Bearer token authentication
• Filter which form fields to include
• Add static key=value pairs to the request
• Configure defaults via system settings, override per form

Installation

Install via the MODX package manager or GPM.

System Settings

Setting	Description	Default
formit-webhook.webhook_url	Default webhook URL	(empty)
formit-webhook.webhook_bearer_token	Default Bearer token for authentication	(empty)
formit-webhook.webhook_method	Default HTTP method	POST
formit-webhook.webhook_static_data	Default static key=value pairs, comma-separated	(empty)

Properties

Properties are set as scriptProperties on the FormIt call. They override the corresponding system settings.

Property	Description	Default
url	The URL to send data to	System setting
token	Bearer token for authentication	System setting
method	HTTP method: GET, POST, PUT, PATCH, DELETE	POST
webhookFormat	Data format: url, form, or json	json
webhookFields	Comma-separated list of form fields to include. Empty = all fields	(all)
webhookVars	Static key=value pairs, comma-separated	System setting

Data Formats

Format	Content-Type	Description
json	application/json	Sends data as a JSON object in the request body
url	application/x-www-form-urlencoded	Sends data as URL-encoded form body
form	multipart/form-data	Sends data as multipart form data

For GET requests, data is always appended as query string parameters regardless of the format setting.

Usage Examples

Basic: Send all fields as JSON POST

[[!FormIt?
    &hooks=`FormitWebhook,redirect`
    &validate=`email:email:required,name:required`
    &redirectTo=`[[++page_thanks]]`
    &url=`https://api.example.com/leads`
    &token=`your-bearer-token`
]]

Filtered fields with static data

[[!FormIt?
    &hooks=`FormitWebhook,redirect`
    &validate=`email:email:required,name:required`
    &redirectTo=`[[++page_thanks]]`
    &url=`https://api.example.com/leads`
    &token=`your-bearer-token`
    &webhookFields=`name,email,phone`
    &webhookVars=`source=website,form_id=contact`
]]

URL-encoded POST

[[!FormIt?
    &hooks=`FormitWebhook`
    &validate=`email:email:required`
    &url=`https://api.example.com/submit`
    &webhookFormat=`url`
]]

GET request

[[!FormIt?
    &hooks=`FormitWebhook`
    &url=`https://api.example.com/notify`
    &method=`GET`
    &webhookFields=`email`
]]

Error Handling

Add the webhook error placeholder to your form template to display errors to users:

[[!+fi.error.webhook:notempty=`
    <p class="error">[[!+fi.error.webhook]]</p>
`]]

Dependencies

• FormIt >= 3.2

License

GPL v2