Webhook Payloads

Each webhook delivery is an HTTP POST request with a JSON body. DocSpring waits up to 30 seconds for your endpoint to respond, and treats any 2xx status code as a successful delivery.

Request headers

Every request includes these headers:

Header	Value
Content-Type	application/json
Accept	application/json
User-Agent	DocSpring/Webhooks
X-DocSpring-Event-Id	The event ID, the same as the body’s id (see Event IDs below)
X-DocSpring-Signature	The signature used to verify the request (see below)

Any custom Headers you configured on the webhook are added as well.

Submission events on a legacy v1/v2 webhook are sent without a signature or event ID and with a DocSpring User-Agent — see Webhook versions below.

Request body

The body is a JSON object with four top-level keys:

{
  "id": "6f1c2e8a-3b4d-4c5e-9f60-7a8b9c0d1e2f",
  "event": "submission.processed",
  "timestamp": "2026-06-27T03:16:07Z",
  "data": {
    "resource": {
      "type": "Submission",
      "id": "sub_0XYZ..."
    },
    "id": "sub_0XYZ...",
    "state": "processed",
    "test": false,
    "template_id": "tpl_0ABC...",
    "download_url": "https://...amazonaws.com/...pdf?X-Amz-Signature=...",
    "metadata": { "customer_id": "cus_123" },
    "data": {
      "name": "Jane Doe",
      "amount": "1234.00"
    }
  }
}

Field	Description
id	The event ID. It stays the same when a delivery is retried.
event	The event type, e.g. submission.processed.
timestamp	UTC ISO 8601 time the event was sent.
data	The event payload (see below).

Every timestamp in the body — timestamp and any *_at field on the serialized resource, such as processed_at or updated_at — is a UTC ISO 8601 string with second precision, e.g. 2026-06-27T03:16:07Z. The same format is used for timestamps in API responses.

The data object

data contains:

• resource — a small pointer to the resource that triggered the event, with its type (e.g. Submission) and id (e.g. sub_0XYZ...).
• The rest of data is the serialized resource itself. For a submission this is the same object the API returns — including its id, state, download_url, metadata, and so on.

The fields in data for each resource type (data.resource.type):

data.resource.type	Fields
Submission	The API’s submission object
CombinedSubmission	The API’s combined submission object
SubmissionBatch	The API’s submission batch object, without its submissions
Template	The API’s template object, as returned when listing templates
SubmissionDataRequest	id, submission_id, name, email, completed_at, fields
Folder	id, name, path, parent_folder_id
CustomFile	id, url
APIToken	id, name, test, revoked_at, created_at
User	id, name, email, created_at, invitation_sent_at, invitation_accepted_at
AccountIntegration	id, service, enabled, created_at, updated_at
Webhook	id

See the API Reference for the fields of the objects the API returns.

Which id is which

The top-level id is the event ID. data.resource.id and data.id are both the resource’s ID, the same one you use with the API. data.resource.id is always sent, even if you remove id with strip fields. Similarly, for submissions the submitted form values live under data.data: the outer data is the event envelope, and the inner data is the submission’s field data.

Event IDs

Every v3 delivery has an event ID, sent as the body’s top-level id and in the X-DocSpring-Event-Id header. The ID stays the same when DocSpring retries a delivery, so you can use it to recognize an event you’ve already processed and ignore the repeat.

Each webhook gets its own event ID. If two of your webhooks receive the same event, their deliveries have different IDs.

Use the body’s id for deduplication. It’s covered by the signature, so it can’t be changed without breaking the signature. The header is a copy for convenience and isn’t signed.

Webhook versions

Every webhook has a version that controls the payload format used for submission events — submission.processed, submission.failed, and the other submission.* events:

Version	Format
v3 (current)	The event envelope shown above (id, event, timestamp, data).
v2 (legacy)	{ "submission": { ... } } — the serialized submission as a JSON object.
v1 (legacy)	A form-encoded body with a single submission field holding the serialized submission as a JSON string.

New webhooks default to v3, which we recommend for all new integrations. The v1 and v2 formats exist only so that endpoints created before the current webhook system keep receiving the exact payloads they were built for.

Versioning only applies to submission events

The version setting only changes the payload for submission events, since those were the only events the legacy formats ever sent. Every other event type — data requests, templates, folders, and so on — is always delivered as v3, even on a v1 or v2 webhook.

Include submission data and strip fields still apply to legacy payloads; they filter the serialized submission before it is wrapped in the v1/v2 envelope. Legacy deliveries are sent with a DocSpring User-Agent and are not signed, matching the original webhook behavior.

Controlling the payload

Include submission data

By default the submitted form values are included (under data.data). If you only need to know that an event happened — and want to avoid sending field data to your endpoint — turn Include submission data off. DocSpring then omits the data.data object from the payload while keeping the rest of the event.

Strip specific fields

Use strip fields to remove individual fields from the payload — for example to keep sensitive values like SSNs or card numbers out of your logs.

List dot-separated paths from the root of the event’s data object. Form field values live under its data key, so a form field is removed with data.<field name>. A bare name removes a whole top-level key, such as metadata or password:

data.ssn
data.card_number
metadata.internal_note
password

The example above removes the ssn and card_number form fields, the internal_note metadata value, and the submission’s password field. Entries that don’t match anything are ignored.

Custom headers

Add custom Headers to every request — for example a static bearer token or a routing header your endpoint expects. Note that custom headers are a convenience, not a security mechanism: always rely on the signature to authenticate requests.