> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vouchmark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create webhook

> Register a webhook subscription for a service.

Creates a webhook subscription that delivers events for one service type to your endpoint.

## Body

<ParamField body="appId" type="string" required>
  Widget / app ID this subscription belongs to. 1–64 characters.
</ParamField>

<ParamField body="environment" type="string" required>
  One of `sandbox` or `live`.
</ParamField>

<ParamField body="serviceType" type="string" required>
  One of `kyc_widget`, `verification`, `trust_monitor`, `disputes`.
</ParamField>

<ParamField body="endpoint" type="string" required>
  Delivery URL. Must be an `http` or `https` URL.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.vouchmark.com/v1/developers/webhooks \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "appId": "...",
      "environment": "live",
      "serviceType": "kyc_widget",
      "endpoint": "https://api.example.com/webhooks/vouchmark"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "...",
      "appId": "...",
      "environment": "live",
      "serviceType": "kyc_widget",
      "endpoint": "https://...",
      "isActive": true,
      "signingSecret": "whsec_...",
      "createdAt": "..."
    }
  }
  ```
</ResponseExample>

Returns `201 Created`.

<Warning>
  The full `signingSecret` is returned **only** on create and [rotate](/api-reference/developers/rotate-webhook-secret).
  Store it securely now — it cannot be retrieved later. List responses return a masked
  `signingSecretMasked` instead. See [Verifying the signature](/webhooks#verifying-the-signature).
</Warning>

## Response fields

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="webhook">
    <ResponseField name="id" type="string" />

    <ResponseField name="appId" type="string" />

    <ResponseField name="environment" type="string">
      One of `sandbox` or `live`.
    </ResponseField>

    <ResponseField name="serviceType" type="string">
      One of `kyc_widget`, `verification`, `trust_monitor`, `disputes`.
    </ResponseField>

    <ResponseField name="endpoint" type="string" />

    <ResponseField name="isActive" type="boolean">
      Whether the subscription is active and receiving deliveries.
    </ResponseField>

    <ResponseField name="signingSecret" type="string">
      The full signing secret (`whsec_...`), returned once. Use it to verify the
      `X-Vouchmark-Signature` header on deliveries.
    </ResponseField>

    <ResponseField name="createdAt" type="string" />
  </Expandable>
</ResponseField>