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 Create and manage webhooks in the DocSpring dashboard

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.
  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.
  • 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.
  • Mode — limit the webhook to test submissions, live submissions, or both.
  • 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.
  • Include submission data — whether to include the submitted form data in the payload. See Webhook Payloads.

You can also manage webhooks through the API. See the API Reference for the POST /api/v1/webhooks endpoint.

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. 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.