Skip to main content
POST
/
v1
/
webhooks
Register a webhook endpoint
curl --request POST \
  --url https://api.example.com/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "enabled": true,
  "events": [
    "humanization.completed",
    "humanization.failed"
  ],
  "url": "https://your-service.example.com/webhooks/kallima"
}
'
{
  "created_at": "2026-04-23T10:00:00+00:00",
  "enabled": true,
  "events": [
    "humanization.completed",
    "humanization.failed"
  ],
  "id": "aaaa0001-bbbb-0002-cccc-000300040005",
  "object": "webhook",
  "updated_at": "2026-04-23T10:00:00+00:00",
  "url": "https://your-service.example.com/webhooks/kallima"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Body for POST /v1/webhooks.

​
url
string
required

HTTPS endpoint Kallima will POST events to.

Example:

"https://your-service.example.com/webhooks/kallima"

​
events
string[] | null

Event types to subscribe to. null or empty list means all events. Example values: humanization.completed, structure_prediction.failed.

Example:
[
  "humanization.completed",
  "humanization.failed"
]
​
enabled
boolean
default:true

Whether deliveries are attempted immediately. Default true.

Response

Successful Response

Registered webhook endpoint.

​
id
string
required

Opaque webhook identifier (UUID).

Example:

"aaaa0001-bbbb-0002-cccc-000300040005"

​
url
string
required

HTTPS endpoint Kallima delivers events to.

Example:

"https://your-service.example.com/webhooks/kallima"

​
enabled
boolean
required

Whether deliveries are being attempted.

​
created_at
string
required

ISO-8601 creation timestamp (UTC).

​
updated_at
string
required

ISO-8601 last-updated timestamp (UTC).

​
object
string
default:webhook

Polymorphic discriminator. Always webhook.

​
events
string[] | null

Subscribed event types. null means all events.

​
secret
string | null

Webhook signing secret. Returned only at creation time — subsequent reads omit this field. Store it immediately; it cannot be recovered. Rotate via PATCH rotate_secret=true.

Example:

"whsec_AbCdEfGhIjKlMnOpQrStUvWx1234567890ABCDEF"