---
title: "Create a signed webhook destination"
description: "Creates a signed generic HTTPS destination with an explicit event-type allowlist and envelopeVersion 2. Requires events.read, webhooks.read, webhooks.write and each selected event-family grant. Wildcards, URL credentials, private destinations, fragments and redirect delivery are unsupported. The signingSecret is revealed only in this response. Registration does not automatically replay historical events. Server credentials only. Application, installation, collection, and TEST/LIVE scope are resolved from the credential. Legacy collection webhook destinations are separate. TEST and LIVE events are isolated; neither event grants charging, booking or marketing authority."
---

`POST /v1/developer/webhook-subscriptions`

**Operation ID:** `createDeveloperWebhookSubscription`

Creates a signed generic HTTPS destination with an explicit event-type allowlist and envelopeVersion 2. Requires events.read, webhooks.read, webhooks.write and each selected event-family grant. Wildcards, URL credentials, private destinations, fragments and redirect delivery are unsupported. The signingSecret is revealed only in this response. Registration does not automatically replay historical events. Server credentials only. Application, installation, collection, and TEST/LIVE scope are resolved from the credential. Legacy collection webhook destinations are separate. TEST and LIVE events are isolated; neither event grants charging, booking or marketing authority.

## Contract status

| Field | Value |
| --- | --- |
| Maturity | `beta` |
| Required capability | `webhooks.write` |
| Freshness class | `authenticated-state` |
| Quota cost | `1` |

All operations require a Kismet Developer Bearer credential. Collection and resource authority is resolved from the credential's installation grants; identifiers in the URL never grant access.

## Request parameters

This operation has no query, path, or explicit header parameters.

## Request body

The request body is JSON. The canonical schema is:

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name",
    "url",
    "eventTypes",
    "envelopeVersion"
  ],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "url": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048
    },
    "eventTypes": {
      "type": "array",
      "minItems": 1,
      "maxItems": 2,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": [
          "payment_method.added",
          "guest.wallet_request.completed"
        ]
      }
    },
    "envelopeVersion": {
      "type": "string",
      "enum": [
        "2"
      ]
    }
  }
}
```

Minimal example:

```json
{
  "name": "string",
  "url": "string",
  "eventTypes": [
    "payment_method.added"
  ],
  "envelopeVersion": "2"
}
```

## cURL

Set `KISMET_API_ORIGIN=https://api.ksmt.app` and configure `KISMET_DEVELOPER_API_KEY` in your environment. Run server-credential requests from your backend, not browser code.

```sh
curl --request POST \
  "$KISMET_API_ORIGIN/v1/developer/webhook-subscriptions" \
  --header "Authorization: Bearer $KISMET_DEVELOPER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"name":"string","url":"string","eventTypes":["payment_method.added"],"envelopeVersion":"2"}'
```

## Responses

| Status | Meaning |
| --- | --- |
| 201 | Created successfully. |
| 400 | Invalid request parameters or body. |
| 401 | Missing, invalid, expired, or inappropriate credential/session. |
| 403 | Credential lacks the required grant/capability, or an origin/CSRF check failed. |
| 404 | The authorized resource was not found. |
| 409 | Request conflicts with the installation environment or current state. |
| 429 | Rate limit or quota exceeded; inspect response metadata before retrying. |
| 503 | A required Kismet dependency is temporarily unavailable. |

### 201 response example

```json
{
  "subscription": {
    "id": "77777777-7777-4777-8777-777777777777",
    "name": "Application events",
    "url": "https://builder.example/webhooks/kismet",
    "eventTypes": [
      "payment_method.added"
    ],
    "enabled": true,
    "envelopeVersion": "2",
    "applicationId": "22222222-2222-4222-8222-222222222222",
    "installationId": "33333333-3333-4333-8333-333333333333",
    "collectionId": "44444444-4444-4444-8444-444444444444",
    "environment": "TEST",
    "secretHint": "abcd",
    "createdAt": "2026-09-23T12:00:01.000Z"
  },
  "signingSecret": "whsec_example_only_store_your_returned_secret"
}
```

### 201 response schema

Content type: `application/json`. Required fields, nullable values, and nested structures are defined below.

<details>
<summary>View complete response schema</summary>

```json
{
  "type": "object",
  "properties": {
    "subscription": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "name": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "eventTypes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "enabled": {
          "type": "boolean"
        },
        "envelopeVersion": {
          "type": "string",
          "enum": [
            "2"
          ]
        },
        "applicationId": {
          "type": "string",
          "format": "uuid"
        },
        "installationId": {
          "type": "string",
          "format": "uuid"
        },
        "collectionId": {
          "type": "string",
          "format": "uuid"
        },
        "environment": {
          "type": "string",
          "enum": [
            "TEST",
            "LIVE"
          ]
        },
        "secretHint": {
          "type": "string",
          "nullable": true
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "name",
        "url",
        "eventTypes",
        "enabled",
        "envelopeVersion",
        "applicationId",
        "installationId",
        "collectionId",
        "environment",
        "secretHint",
        "createdAt"
      ],
      "additionalProperties": false
    },
    "signingSecret": {
      "type": "string"
    }
  },
  "required": [
    "subscription",
    "signingSecret"
  ],
  "additionalProperties": false
}
```

</details>

## Machine-readable sources

- [This page as Markdown](/api/reference/create-developer-webhook-subscription.md)
- [Developer API OpenAPI v0.7.25](/openapi.json)