Kalpana Docs

POST /api/webhooks

Requires webhooks:create, the workspace Owner role (or an Owner's API key), and an active subscription. An endpoint with source set to zapier or n8n can be added by any member with webhooks:create. See Endpoints.

Name	Type	Required	Description
`workspace`	string	Yes	Workspace slug or id.
`name`	string	Yes	1 to 100 characters.
`url`	string	Yes	A public `https://` URL of up to 2048 characters, on port 443 or 1024 and above, with no username or password.
`events`	string[]	Yes	1 to 20 event types from List event types, or `["*"]`.
`filters`	object	No	`{ "templateIds": [...] }`, up to 50 template ids, to send only events of those templates.
`format`	string	No	`json`, `slack`, `discord` or `google_chat`. Omit to choose from the URL: Slack, Discord and Google Chat incoming webhooks get their message shape, anything else `json`.
`authHeader`	object	No	`{ "name": "Authorization", "value": "Bearer ..." }`, sent on every request. See the rules in Endpoints.
`description`	string	No	Up to 500 characters.
`source`	string	No	`zapier` or `n8n` when an automation app subscribes a member's own Zap or workflow. Any member may add these, no test event is sent, and each app has its own limit of 50.

curl --request POST "https://app.kalpana.one/api/webhooks" \
  --header "x-api-key: $KALPANA_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "workspace": "acme",
    "name": "Zapier: new creatives",
    "url": "https://hooks.zapier.com/hooks/catch/123/abc/",
    "events": ["batch.completed"]
  }'

Response

The endpoint object plus signingSecret and test:

{
  "id": "0192f8a4-6c1e-7c3a-9b0e-4d2f1a7e5c11",
  "name": "Zapier: new creatives",
  "description": null,
  "url": "https://hooks.zapier.com/hooks/catch/123/abc/",
  "events": ["batch.completed"],
  "filters": {},
  "format": "json",
  "apiVersion": "2026-10-20",
  "authHeaderName": null,
  "source": "api",
  "enabled": true,
  "disabledAt": null,
  "disabledReason": null,
  "health": { "consecutiveFailures": 0, "failingSince": null },
  "createdAt": "2026-10-20T09:41:07.512Z",
  "updatedAt": "2026-10-20T09:41:07.512Z",
  "signingSecret": "whsec_...",
  "test": {
    "deliveryId": "0192f8a4-7d2e-7a10-8c3b-5e1f2a9d4b22",
    "status": "succeeded",
    "responseStatus": 200,
    "durationMs": 342,
    "error": null
  }
}

signingSecret: store it now. An API key cannot read it again. A signed-in member can show it later in the Studio, and an Owner can rotate it there.
test: the result of a test event sent to the URL as the endpoint is created, in the shape of Send a test event. If the URL answers 405 or 410, the endpoint is already turned off. It is null for a zapier or n8n endpoint, which gets no test event, and when the test could not be sent.

source is api for an endpoint added with an API key, and studio for one added in the Studio.

Errors

Status	Cause
`400`	A field is not valid, such as an unknown event type, a URL that is not public `https`, or a reserved auth header name.
`402`	The workspace's organization has no active subscription.
`403`	Your role or key lacks `webhooks:create`, or you are not the workspace Owner and `source` is not `zapier` or `n8n`.
`409`	The workspace has reached its limit of endpoints for that source, or another endpoint already sends to this URL. `message` names it.

Add an endpoint

Response

Errors

On this page