Incoming webhooks

An incoming webhook is a secret URL that posts into one fixed channel as the Kit bot. It is the simplest way to send notifications from CI, monitoring or any script: no token, no backend, one HTTP request.

Setup

1. The Kit’s manifest requests the incoming-webhook bot scope and declares how many webhooks an installation may have:

   {
     "bot": { "displayName": { "en": "Acme CI" }, "scopes": ["incoming-webhook"] },
     "incomingWebhooks": { "maxPerInstallation": 5 }
   }

   maxPerInstallation is 1 to 20.

2. An admin opens the Kit’s API access page and creates a webhook for a channel. The admin must be a member of that channel. The Kit bot is added to the channel.

3. The URL is shown once:

   https://hooks.ketvia.com/v1/{installationId}/{webhookId}/{secret}

   The URL is the credential. Treat it like a password: keep it in a secret store (for example a CI secret named KETVIA_WEBHOOK_URL), never in source code, logs or chat.

Posting

curl -s -X POST "$KETVIA_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "Build #42 passed on main",
    "blocks": [
      { "type": "header", "text": "Build #42 passed" },
      {
        "type": "fields",
        "fields": [
          { "label": "Branch", "value": "main" },
          { "label": "Duration", "value": "3m 12s" }
        ]
      }
    ]
  }'

The body:

Field	Type	Rules
text	string	Required, 1 to 4000 characters, not blank. Used for notifications and search.
blocks	array	Optional Blocks. Interactive elements are removed: a webhook has no endpoint to receive clicks.

Other keys (channel, username, icon and so on) are ignored: a webhook always posts as the Kit bot into its own channel. Image blocks may only reference a Ketvia file visible in that channel.

With the SDK:

import { blocks, postToWebhook } from '@ketvia/kit';

await postToWebhook(process.env.KETVIA_WEBHOOK_URL ?? '', {
  text: 'Build #42 passed on main',
  blocks: [blocks.header('Build #42 passed'), blocks.fields({ Branch: 'main' })],
});

postToWebhook retries after 429 (honouring Retry-After) but not after network errors or 5xx: a webhook post has no idempotency key, so a blind retry could post twice.

Responses

Status	Body	Meaning
200	{"ok":true}	Posted.
400	{code, message, correlationId}	Invalid body (for example text missing or too long, or invalid Blocks).
404	{code, message, correlationId}	Unknown, revoked or uninstalled webhook. The three cases get the same answer on purpose.
410	{code: "gone", …}	The webhook is disabled because its channel was archived or the Kit bot was removed from it.
413	{code: "payload_too_large", …}	The body is over 64 KB.
429	{code: "rate_limited", …}	Over 1 request per second sustained (burst 5). Wait Retry-After seconds.

A 410 is permanent: create a new webhook for a channel the Kit bot can post in. A 404 is also permanent; stop sending and ask an admin for a new URL.

Revoking

Admins revoke a webhook on the Kit’s API access page. The URL answers 404 at once. To “regenerate” a URL, revoke the old webhook and create a new one. Uninstalling the Kit disables all its webhooks.

See the ci-webhook sample for a complete GitHub Actions setup.