Webhooks

A webhook endpoint is an HTTPS address of yours that K-Block Cloud notifies with a signed HTTP POST when something happens in your organization: an approval is requested, a call is decided, an execution finishes, a receipt is created, a policy version is activated or an observe window starts or ends.

Use webhooks to feed approvals into your own chat or ticketing tools, to alert on denied calls, or to keep a copy of events in your own systems. This page covers the Webhooks pages of the dashboard. How deliveries are signed, retried and verified is described in Webhook delivery, and every event's payload in Webhook events.

Who can manage webhooks

Owners, admins and developers see Webhooks in the navigation and can do everything on these pages. Approvers and viewers cannot even list endpoints: the Cloud API refuses them. Management API keys can never read or change webhooks.

Create an endpoint

1. Open the form

   Go to Webhooks and select New endpoint.

2. Enter the address

   • Endpoint URL: an https:// URL, up to 2,048 characters, without a fragment (#…) and without a user name or password.
   • Description (optional): up to 500 characters, for example which system receives the events.

   K-Block only delivers to public https:// addresses. The Cloud API resolves the host name and checks every address it resolves to. Private, loopback and other internal addresses, and plain http://, are refused with URL_NOT_ALLOWED (HTTP 422): use a public https:// address that your receiver answers on. Redirects are never followed: a 3xx answer counts as a failed attempt.

3. Choose the events

   All 13 subscribable event types are selected by default. Clear the ones you do not want; at least one must stay selected. Select all and Clear change the whole selection.

4. Create it and store the secret

   Leave Enabled checked and select Create endpoint. The endpoint's signing secret (whsec_…) is shown once, under Signing secret of the new endpoint. Store it in your receiver's configuration, then select I have stored it — hide.

The event types

The form groups the types by what they are about. These are the same 13 types the Cloud API accepts.

policy.activated is sent for every change of a policy's active version: an activation, a promoted shadow version, a rollback and an emergency stop. action.observe_override is sent once for every call that an observe window allowed although the policy said otherwise, so it can be frequent while a window is open.

A fourteenth type, webhook.test, cannot be subscribed to. It is sent only when you select Send test event, and only to that endpoint.

The endpoint list

Webhooks lists every endpoint with its URL and description, the number of subscribed events, its state (Enabled or Disabled), its deliveries (failed and pending counts) and its creation date. With two or more endpoints, a summary line counts the endpoints with failed deliveries, enabled and disabled.

Below the list, Receiving deliveries summarizes what your receiver must do with every delivery:

1. Verify the KBlock-Signature header with the endpoint's signing secret.
2. Refuse deliveries whose timestamp is more than 5 minutes away from your clock.
3. Deduplicate on KBlock-Event-Id: delivery is at least once, so the same event can arrive again.

Webhook delivery explains the signature format and gives verification code.

Send a test event

Open an endpoint and select Send test event. K-Block queues a webhook.test event for that endpoint alone, whatever events it subscribes to, and delivers it like any other event. The page says "A webhook.test event was queued. Its delivery appears below."

The button is disabled while the endpoint is disabled ("Enable the endpoint to send a test event."). Test events and redeliveries together are limited to 5 per minute per endpoint; more answer RATE_LIMITED.

Read the delivery log

The Deliveries card lists the endpoint's deliveries, newest first. It shows the latest 10; Show older deliveries shows the rest of those loaded, and Load more then reads older ones. Each row shows:

• Event: the event type.
• Status: Pending, Succeeded or Failed.
• Attempts: how many times K-Block tried.
• Last response: the HTTP status your receiver answered, or No response, with the error for a delivery that did not succeed.
• Last attempt: when it was last tried, when a pending delivery is tried next, and the full attempt log (time, status or error, duration) when there is more than one attempt or the attempt failed.

When failures exist, All and Failed filter the list. The list does not refresh by itself: select Refresh to read it again.

Only a 2xx answer counts as success. A failed attempt is retried with exponential backoff, up to 8 attempts in total; after that the delivery is Failed.

Redeliver a failed delivery

A failed delivery shows Redeliver under its status. Selecting it queues the same delivery again with 8 new attempts; its earlier attempts stay in the log. Only failed deliveries can be redelivered, and only while the endpoint is enabled. On a disabled endpoint the page says "Enable the endpoint to redeliver failed deliveries."

Edit, enable or disable an endpoint

The Settings card holds the same form as creation: URL, description, events and Enabled. Change what you need and select Save endpoint. Saving replaces the endpoint's event list with the boxes checked in the form, so at least one listed type must be checked; otherwise the form says "Choose at least one event." and saves nothing. If the endpoint also receives a type the form does not list, a notice names it and says that saving keeps only the events selected in the form.

Uncheck Enabled to pause delivery without deleting the endpoint:

• Events that happen while it is disabled are not queued for it, and are not sent later.
• Deliveries already pending when you disabled it wait, and are sent after you enable it again.
• Failed deliveries cannot be redelivered and test events cannot be sent until you enable it.

Rotate the signing secret

In the Signing secret card, select Rotate secret and confirm. The new secret is shown once, under New signing secret.

For the next 24 hours every delivery is signed with both the new and the previous secret, so your receiver keeps verifying while you switch it to the new one. After that, only the new secret signs. Rotate whenever a secret may have leaked.

Delete an endpoint

In the Delete this endpoint card, select Delete endpoint and confirm. The endpoint and its whole delivery history are deleted, including pending deliveries. This cannot be undone. The audit log keeps a webhook.deleted event with the endpoint's host.

Limits and audit

• The number of endpoints is limited by the plan (2 on the free Developer plan). Creating one over the limit fails with PLAN_LIMIT_EXCEEDED; see Billing.
• Creating, changing (a secret rotation included), deleting, testing and redelivering are recorded in the audit log (webhook.created, webhook.updated, webhook.deleted, webhook.test_sent, webhook.redelivered).

Related pages