A webhook transmits each valid form submission to an external URL. Drupal Canvas Forms never triggers a webhook for suspect requests, invalid requests, or rate-limited requests. To maintain strict security, Drupal Canvas Forms validates the destination URL against server-side request forgery upon save and during each delivery. The system explicitly rejects URLs that resolve to private addresses, loopback addresses, or link-local addresses. Administrators must refer to this document to define a destination endpoint, establish a cryptographic secret, send test payloads, and verify delivery status. This document provides instructions to configure webhooks for Drupal Canvas Forms. 

Prerequisites

• Ensure that an administrator account has the Administer Drupal Canvas Forms permission to configure webhooks.

  For more information, visit Managing permissions.

Configure a webhook

To configure a webhook:

1. Open Drupal Canvas forms.

A webhook transmits each valid form submission to an external URL. Drupal Canvas Forms never triggers a webhook for suspect requests, invalid requests, or rate-limited requests. To maintain strict security, Drupal Canvas Forms validates the destination URL against server-side request forgery upon save and during each delivery. The system explicitly rejects URLs that resolve to private addresses, loopback addresses, or link-local addresses. Administrators must refer to this document to define a destination endpoint, establish a cryptographic secret, send test payloads, and verify delivery status. This document provides instructions to configure webhooks for Drupal Canvas Forms. 

Prerequisites

• Ensure that an administrator account has the Administer Drupal Canvas Forms permission to configure webhooks.

  For more information, visit Managing permissions.

Configure a webhook

To configure a webhook:

1. Open Drupal Canvas forms.
2. Open the form and select Webhooks.
3. Enter the destination URL in the Endpoint URL field, for example, https://example.com/webhook. Leave the field empty to send nothing.
4. Enter a secret in the Signing secret field. When an administrator sets this secret, each delivery includes an X-Canvas-Forms-Signature header so that the receiver can verify the request.
5. Select Save.

Drupal Canvas Forms validates the URL against server-side request forgery upon save and during each delivery. Drupal Canvas Forms rejects URLs that resolve to private, loopback, or link-local addresses. Because Drupal Canvas Forms re-validates the URL at delivery time and pins the connection to the validated address, a URL cannot pass validation and then point to an internal address. Drupal Canvas Forms stores the signing secret securely on the server and never displays it again. Share the same secret with the receiver to verify deliveries.

Test a webhook and view deliveries

After an administrator configures a webhook URL, the Webhooks tab provides options to send a test delivery and review recent deliveries.

To test a webhook and view deliveries:

1. Open Drupal Canvas forms.
2. Open the form and select Webhooks.
3. Select Send test to send a test payload to the configured URL, and then check the result.

4. Review Recent deliveries for the form, which lists the HTTP status, timing, and response for each delivery. This review helps administrators confirm that a receiver accepts submissions or diagnose a failure.

   Delivery runs in the background and retries automatically on connection errors and server errors.

Verify Webhook Signatures

When an administrator sets a signing secret, each webhook request carries the following headers:

To verify a request, compute the HMAC-SHA256 of the raw request body with the form signing secret and compare it to the value after sha256=.

The delivered JSON payload has this shape:

{
  "event": "submission.created",
  "table": "contact_form",
  "submission_id": 42,
  "data": { "field_name": "value", "...": "..." },
  "ip": "1.2.3.4",
  "timestamp": 1718000000
}

The data object contains the validated submission values. File fields deliver as file metadata plus a presigned, time-limited download URL, valid for seven days, that a receiver can fetch without a Drupal session. The payload includes the ip field only if the form stores submitter IP addresses.