Skip to content
DocSpring Documentation

Webhooks Overview

Webhooks let DocSpring notify your application in real time when something happens in your account — for example, when a PDF finishes generating, a data request is completed, or a submission fails. Instead of polling the API, you register an HTTPS endpoint and DocSpring sends it a POST request for each event you subscribe to.

Manage webhooks (US) Create and manage webhooks in the DocSpring dashboard
Manage webhooks (EU) Create and manage webhooks for your EU account

How it works

Section titled “How it works”
  1. You create a webhook with a destination URL and a list of events.
  2. When a matching event occurs, DocSpring sends a signed POST request to your URL with a JSON payload describing the event. (Submission events on a legacy v1/v2 webhook are not signed. See Webhook versions.)
  3. Your endpoint responds with a 2xx status code to acknowledge receipt.
  4. If your endpoint fails, DocSpring retries with an exponential backoff for up to three days. See Delivery, Retries & Failures.

Creating a webhook

Section titled “Creating a webhook”

In the dashboard, go to Webhooks → Create Webhook and fill in:

  • Name: an optional label to help you identify the webhook.
  • Webhook URL: the HTTPS endpoint that will receive events.
  • Mode: limit the webhook to test submissions, live submissions, or both.
  • Webhook Version: the payload format for submission events. Use v3 (the default); v1 and v2 are legacy formats. See Webhook versions.
  • Include submission data: whether to include the submitted form data in the payload. See Webhook Payloads.
  • Enabled: uncheck to stop deliveries without deleting the webhook.
  • Send failure notification emails: whether DocSpring emails you when this webhook is failing. See Failure notifications.
  • Events: the events that should trigger this webhook. A sensible default set is pre-selected; use the All / None links to toggle a whole group at once.
  • Scope: optionally limit the webhook to specific API tokens, templates, or folders by listing their IDs. Leave blank to receive events for everything. See Events.
  • Headers: optional custom HTTP headers to include with every request.
  • Strip Fields: paths to remove from the payload. See Strip specific fields.

You can also manage webhooks through the API:

API Reference: Webhooks Create, list, update, and delete webhooks with the API

The signing secret

Section titled “The signing secret”

Every webhook is created with a unique signing secret (a 64-character hex string). DocSpring uses it to sign each request so you can verify the payload really came from DocSpring and was not tampered with.

You can find the secret on the webhook’s detail page in the dashboard, and it is also returned as the secret field on every webhook API response.

Learn how to use the secret in Verifying Signatures.

Enabling, disabling, and deleting

Section titled “Enabling, disabling, and deleting”

From the dashboard you can disable a webhook to temporarily stop deliveries without deleting it, then enable it again later. Events that occur while a webhook is disabled are not sent later, and retries that come due while it’s disabled are dropped. Deleting a webhook stops all future deliveries permanently.

DocSpring will also automatically disable a webhook after it has been failing continuously for three days. See Delivery, Retries & Failures.