Create a signed webhook destination

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:

{
  "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:

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

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

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

View complete response schema

{
  "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
}