Webhooks

2 min read

Webhooks connect an agent to any system that exchanges events over HTTP: automations, internal platforms, monitoring tools, or your own applications. A channel can receive events, send requests, or do both.

Receive only

An external system POSTs to a unique Kujira URL. This is the usual option for notifications and events.

Send only

The agent publishes its replies or actions to an external URL. It requires an outbound URL.

Receive and reply

Combines both directions: the agent processes incoming events and can return an action to the originating system.

Create the channel

Define channel direction

In the agent's Channels, add a webhook and choose whether it receives events, sends requests, or does both. Send-only channels need an outbound URL before they can be saved.

Configure outbound delivery when needed

Add the public URL to which the agent will POST. If the external system needs to verify the origin, also define a signing secret.

Save and copy the inbound URL

Kujira generates a secret URL for incoming events. Copy it into the system that emits events; do not enter it manually in Kujira.

Describe the event to the agent

Add instructions describing the format, relevant events, and what action the agent should take for each one.

Identify the origin

You can append a suffix to the inbound URL to label events from different tools. One configuration can receive events through paths such as /clickup, /sentry, or /deployments. Kujira keeps that source so the agent can interpret where each event came from.

The secret URL authenticates the channel by itself. There is no allow list for webhooks: control access through the URL and, when supported by the sender, an HMAC signature.

Sign and verify events

To strengthen inbound delivery, configure a verification secret and the header name that carries the signature. When a secret is set, every POST must include a valid HMAC-SHA256 signature calculated over the unmodified body; the default header is x-kujira-signature.

Kujira accepts the usual hexadecimal value and the sha256= prefix. This allows providers using headers such as x-plane-signature or x-hub-signature-256 without changing verification.

Outbound requests use an independent secret. When you define one, Kujira signs every POST with HMAC-SHA256 in the x-kujira-signature header so the receiving system can verify that it came from the channel.

Avoid exposing secrets

Do not share the inbound URL or signing secrets in public documentation, chats, or repositories. Rotate them if you suspect exposure.

Response and processing

By default, Kujira accepts the event and returns immediately while the agent processes it in the background. If the sender needs the agent's response in the same request, add ?wait=1 to the URL: Kujira waits up to 25 seconds and returns 202 Accepted if the agent takes longer while work continues.

Set the echo filter when an agent action can generate another event to the same webhook. Specify the body paths that identify the author or your own identifiers so the channel discards that activity and avoids a loop.

Check the integration

Run a minimal test

Send a test JSON POST to the inbound URL and confirm that a conversation or event appears for the agent. Include the signature when you configured a secret.

If you receive 401

Review the secret, configured header, and that the HMAC is calculated from the original body without reformatting before signing.

If the agent cannot reply

Check the outbound URL, its public availability, and outbound signature settings. An inbound-only channel does not make reply POSTs.

Check the outbound side with one click

The **Test** button on the channel's card delivers a test message to your outbound URL, signed like any other. The text says it is a test, and Kujira warns you before sending it.