---
title: "Configuring webhooks"
date: "2026-07-14T09:36:04+00:00"
summary: "Set up secure webhooks in Drupal Canvas Forms—configure endpoints, signing secrets, and verify deliveries with ease."
image:
type: "page"
url: "/source-cms/configuring-webhooks"
id: "12a3eb39-89ff-4329-9837-2d9aa6e12032"
---

Table of contents will be added

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](/source-cms/managing-permissions "Managing permissions").
    

Configure a webhook
-------------------

To configure a webhook:

1.  [Open Drupal Canvas forms](/source-cms/creating-and-managing-forms "Creating and managing forms").
2.  Open the form and select **Webhooks**.
3.  Enter the destination URL in the **Endpoint URL** field, for example, [https://example.com/webhook](https://www.google.com/search?q=https://example.com/webhook). Leave the field empty to send nothing.
4.  Enter a secret in the **Signing secre**t 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](/source-cms/creating-and-managing-forms "Creating and managing 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:

Header

Value

`Content-Type`

`application/json`

`User-Agent`

`Canvas-Forms-Webhook/1.0`

`X-Canvas-Forms-Event`

`submission.created` for a real submission, or `test` for a test delivery.

`X-Canvas-Forms-Signature`

`sha256=<hmac>`, an HMAC-SHA256 of the raw request body computed with the signing secret of the form.

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.