# Webhooks for Contact Form 7 — Usage Documentation

## Overview
Webhooks for Contact Form 7 allows you to send Contact Form 7 submissions to a specified webhook URL. This enables integration with various external services and automation tools.

## Installation
1. Download Webhooks for Contact Form 7 from the WordPress Plugin Directory or your repository.
2. Upload the `webhooks-for-contact-form-7` folder to your WordPress plugins directory.
3. Activate the plugin via the WordPress admin dashboard.

## Configuration
1. Navigate to **Settings > WBHKS Webhook** in your WordPress admin.
2. Enter your webhook URL in the provided field.
3. Optionally, set a Bearer token for authentication.
4. Save your changes.

## Per-form mode (one webhook per form)
If you choose the "One webhook per form" mode in Settings you'll be able to configure a separate webhook URL and an optional Bearer token for each Contact Form 7 form found on your site. This is useful when different forms should post to different endpoints or services.

- Go to **Settings > WBHKS Webhook**.
- Select the "One webhook per form" radio option.
- For each form in the list, enter the webhook URL you want that form to post to and an optional Bearer token. Leave a form's URL empty to fall back to the global webhook (if configured).

The plugin sends a JSON payload that includes `form_title`, `page_url`, and all submitted fields. You can also add additional field names (one per line) in the per-form settings; those fields will be included as `additional_<field_name>` in the payload.

### Visual guide
The screenshots below show the per-form settings and the WordPress admin menu entry.

![Settings page showing mode selection and per-form webhook fields](../images/cf7-webhook-settings.png)

![WBHKS Webhook entry in the WordPress admin menu](../images/cf7-webhook-tools-settings.png)

Notes:
- If you set a Bearer token for a specific form, it will be used instead of the global token for that form's webhook request.
- If a per-form URL is empty, the plugin falls back to the global webhook URL (when in global mode that URL must be set).

## Usage
Once configured, the plugin will automatically send form submissions to the specified webhook URL whenever a form is submitted.

### Example Webhook Payload
The data sent to your webhook will include:
- `form_title`: The title of the submitted form.
- `page_url`: The URL of the page where the form was submitted.
- All form fields and their values.

### Additional Fields
You can configure additional fields to be sent with the webhook by specifying them in the plugin settings. These fields will be included in the payload under the key `additional_<field_name>`.

## Troubleshooting
- Ensure your webhook URL is correct and accessible.
- Check for conflicts with other plugins.
- Review WordPress logs for any errors related to the webhook.

## Webhook Logs

The plugin provides a built-in log viewer to inspect recent webhook delivery attempts and responses.

- Where to find logs: Go to **Settings → WBHKS Webhook** in the WordPress admin. The Logs section appears below the plugin settings form.
- What the logs show: each entry includes the timestamp, form title and ID, delivery status (success / failed / skipped), HTTP status code (if present), the webhook URL used, a short message, and a truncated response body preview (up to ~1000 characters).
- Storage and retention: Logs are stored in the WordPress options table (`wbhks_webhook_logs`) and the plugin keeps the most recent 200 entries by default. You can change the limit in the source if needed (`WBHKS_Webhook::LOG_LIMIT`).
- Clearing logs: Use the **Clear Logs** button on the settings page. This action is protected by a capability check and a nonce to prevent unauthorized clearing.
- Privacy: Submitted form values are not logged directly. Endpoint response previews, error messages, and webhook URLs can contain personal or sensitive data. Use trusted endpoints and clear logs when appropriate.

## Support
For further assistance, please contact support at [geral@rumostudio.pt](mailto:geral@rumostudio.pt) or open an issue on our GitHub repository.