Skip to content
Kalipto Devs Platform — API Docs

Create Subscription

POST
/platform/v1/webhooks/subscriptions
 
curl --request POST \
  --url https://example.com/platform/v1/webhooks/subscriptions \
  --header 'Content-Type: application/json' \
  --data '{ "buffer_max_batch": 1, "buffer_window_seconds": 1, "custom_headers": { "additionalProperty": "example" }, "description": "example", "event_types": [ "example" ], "inactivity_minutes": 1, "is_active": true, "platform_channel_id": 1, "target_url": "https://example.com" }'

Create a normalized webhook subscription.

  • target_url is SSRF-validated at create time (https-only + public IP).
  • event_types validator (in the schema) rejects unknown values with 422.
  • platform_channel_id, when set, must belong to this account (422 on miss).
  • The plaintext secret is returned ONCE in this response and Fernet- encrypted at rest.

Request Body required

Section titled “Request Body required ”
Media type application/json
PlatformWebhookSubscriptionCreate

Input for creating a normalized subscription.

event_types=[] -> all events EXCEPT PLATFORM_WILDCARD_EXCLUDED_EVENTS. platform_channel_id NULL -> account-level (all the account’s channels). Pydantic HttpUrl enforces parse-able URL; the dispatcher’s SSRF guard enforces https + public-IP at create time (raised as 422 by the endpoint).

object
buffer_max_batch
Any of:
integer
>= 1 <= 100
buffer_window_seconds
Any of:
integer
>= 1 <= 60
custom_headers
Any of:
object
key
additional properties
string
description
Any of:
string
<= 200 characters
event_types
Event Types

Event types to filter on. Empty list = catch-all (every event EXCEPT message.received, which only an explicit subscription receives). Known event types: channel.connected, channel.disconnected, conversation.created, conversation.ended, conversation.inactive, message.delivered, message.echo, message.failed, message.read, message.received, message.sent, template.status_changed.

Array<string>
inactivity_minutes
Any of:
integer
>= 1 <= 1440
is_active
Is Active
boolean
default: true
platform_channel_id
Any of:
integer
target_url
required
Target Url
string format: uri
>= 1 characters <= 2083 characters

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Successful Response

Media type application/json
PlatformWebhookSubscriptionCreateResponse

Returned only at create / rotate-secret. secret shown ONCE.

object
buffer_max_batch
Any of:
integer
buffer_window_seconds
Any of:
integer
created_at
Any of:
string format: date-time
custom_headers
Any of:
object
key
additional properties
string
description
Any of:
string
developer_account_id
required
Developer Account Id
integer
event_types
Event Types
Array<string>
failure_count
required
Failure Count
integer
id
required
Id
integer
inactivity_minutes
Any of:
integer
is_active
required
Is Active
boolean
is_paused
required
Is Paused
boolean
last_delivery_at
Any of:
string format: date-time
paused_reason
Any of:
string
platform_channel_id
Any of:
integer
secret
required
Secret
string
target_url
required
Target Url
string
updated_at
Any of:
string format: date-time
Example generated
{
  "buffer_max_batch": 1,
  "buffer_window_seconds": 1,
  "created_at": "2026-04-15T12:00:00Z",
  "custom_headers": {
    "additionalProperty": "example"
  },
  "description": "example",
  "developer_account_id": 1,
  "event_types": [
    "example"
  ],
  "failure_count": 1,
  "id": 1,
  "inactivity_minutes": 1,
  "is_active": true,
  "is_paused": true,
  "last_delivery_at": "2026-04-15T12:00:00Z",
  "paused_reason": "example",
  "platform_channel_id": 1,
  "secret": "example",
  "target_url": "example",
  "updated_at": "2026-04-15T12:00:00Z"
}

422

Section titled “422 ”

Validation Error

Media type application/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Example generated
{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}