---
title: "Create a webhook"
method: POST
path: "/webhooks"
tags: ["Webhooks"]
---

# Create a webhook

`POST /webhooks`

Creates a webhook that delivers a POST request to your endpoint whenever a subscribed event
occurs. Optionally scope the webhook to specific API tokens, templates, or folders.

## Request body

- object
  - `webhook` object, required
    - `api_token_uids` string[] — Only deliver events from these API token IDs. Combined with the other scope lists using OR. Applies to submission, data request, combined submission, submission batch, and file events; subscribing to other event types while this filter is the only applicable one returns a validation error.
    - `enabled` boolean
    - `event_types` string[], required — Event types this webhook subscribes to.
    - `folder_uids` string[] — Only deliver events related to these folder IDs, including their subfolders (folder scoping is hierarchical). Combined with the other scope lists using OR. Applies to submission, data request, template, and folder events; subscribing to other event types while this filter is the only applicable one returns a validation error.
    - `headers` object — Custom headers to send with each request.
    - `include_submission_data` boolean — Include submission field data in the payload.
    - `mode` 'test' | 'live' | 'null', nullable — Limit deliveries to test or live submissions. Null delivers both.
    - `name` string, nullable
    - `strip_fields` string[] — Dot-separated paths to remove from the event's data object. Form fields live under data (e.g. data.ssn removes the ssn form field); a bare name removes a top-level key (e.g. metadata removes the whole metadata object).
    - `template_uids` string[] — Only deliver events related to these template IDs. Combined with the other scope lists using OR. Applies to submission, data request, and template events; subscribing to other event types while this filter is the only applicable one returns a validation error.
    - `url` string, uri, required — The endpoint that receives webhook POST requests.
    - `version` 1 | 2 | 3 — Payload format for submission events (1/2 legacy, 3 current). Defaults to 3.

## Response `201`

webhook created

- Webhook
  - `uid` string, required
  - `name` string, nullable, required
  - `url` string, nullable, required
  - `enabled` boolean, required
  - `event_types` string[], required
  - `mode` 'test' | 'live', nullable, required
  - `version` 1 | 2 | 3, required
  - `api_token_uids` string[], required
  - `template_uids` string[], required
  - `folder_uids` string[], required
  - `include_submission_data` boolean, required
  - `strip_fields` string[], required
  - `headers` object, required
  - `consecutive_failures` integer, required
  - `last_failure_at` string, nullable, required
  - `disabled_at` string, nullable, required
  - `disabled_reason` string, nullable, required
  - `secret` string, nullable, required
  - `created_at` string, nullable, required
  - `updated_at` string, nullable, required

## Other responses

- `401` — authentication failed
- `422` — invalid parameters

---

[API](https://skmtc.dev/docspring/apis/docspring-api.md) · [All operations](https://skmtc.dev/docspring/apis/docspring-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/docspring/docspring-api/revisions/5726657b9432/schema)