DocuSeal sends webhook events when forms are viewed, started, completed, or declined, and when templates are created, updated, or archived. The API documentation says failed webhook requests are retried multiple times within 48 hours. The DocuSeal guide also describes adding a configured secret key-value pair to webhook request headers. Those facts make the receiver responsible for authenticity, replay handling, and idempotency.
The secret header is not a complete protocol
A configured secret header can help a receiver reject requests that do not know the value. It does not automatically define a signature over the body, a timestamp window, or a one-time event identifier. Verify the actual implementation before designing around stronger assumptions. Keep the secret out of URLs and browser-visible code, compare values in constant time where the receiver supports it, and reject missing or duplicate headers.
Because DocuSeal retries failures, the receiver must tolerate a repeated event. Store the event type and stable identifiers from the payload and make processing idempotent. A duplicate form.completed event should not create a second signed-document record or send a second customer notification.
Routing and data exposure
Webhook URLs are part of the integration's network policy. Prefer a dedicated endpoint with a narrow route rather than a shared webhook handler that can dispatch arbitrary event types. Validate the payload schema, enforce a size limit, and do not trust a URL supplied by an unauthenticated form submission.
The event payload may contain template names, submitter identifiers, field metadata, and document references. Restrict who can read the receiver's logs and queued jobs. Redact signatures and personal data that are not needed for processing. If the receiver forwards events to another service, keep a separate credential for that hop.
Exposure evidence
A ZoomEye count-only query for app="DocuSeal" returned 2,301 results on 2026-11-08 using sub_type=all, page 1, and page size 1. The title query returned 2,273 and the body query 439,276. The body count is broad, and none of the observations establishes that a webhook endpoint is reachable or lacks a secret.
Search link: ZoomEye application query
Verification plan
Send a valid test event and confirm that the receiver records it once. Send the same event again and verify that the duplicate is accepted as a retry but does not repeat side effects. Remove the secret header and confirm rejection. Send an event for an unknown template or submitter and confirm that the receiver does not create a privileged record by default.
After a receiver change, replay a previously successful but stale event. The policy should make the result predictable, whether the receiver rejects it as too old or treats it as an idempotent duplicate. Finally, rotate the secret in DocuSeal and the receiver together. Keep the old value only for a bounded overlap window.
References
- 1.
- 2.
- 3.