Webhooks
4 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
Send only
Receive and reply
Create the channel
Define channel direction
Configure outbound delivery when needed
Save and copy the inbound URL
Describe the event to the agent
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.
Tell each person apart
On an External webhook, events can come from different customers: a CRM, a shop, or a contact form. Without further setup, everything arriving through one source is a single contact. In the Contacts section of the channel, you can indicate which body fields hold the details of whoever writes, and each person gets their own contact and their own conversation in Agent Desk.
| Field | What it is for |
|---|---|
| ID paths | Identifies the person. It is the only required one: without it, the section is off. |
| Name paths | Name the contact appears with. |
| Email paths and Phone paths | Contact details stored with the person. |
Each path uses dots to reach into the JSON: customer.id reads the id field inside customer. You can write several comma-separated paths; the first one with a value is used, so one channel can receive two event formats. Because the mapping adapts to what your system already sends, you do not need to change the sender.
Before saving, Try with the latest events shows who the last five events received would come from with the paths you entered. While editing, the fields suggest the paths found in the latest event.
These conversations follow Agent Desk rules: when someone on the team takes over the contact, the agent stops replying. An event without an id goes to the source contact, as without setup, and so does any event after 100 new people within an hour on the same channel. The id can be up to 200 characters and must be a simple value, not an object. On an Internal channel, this section does not appear and the mapping does not apply.
Set up the inbound signature
Each person's id comes from the event body. Without a verification secret, anyone who knows the URL can write on behalf of any contact. The panel warns you while the mapping is on without a 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. If someone on the team is handling the contact, the response is an immediate 202 Accepted, because the agent will not reply.
With Contacts set up, the replies the agent sends to the outbound URL say whom they are for: next to the text, the body includes the source and the person's id ({ "text": "…", "contact": { "source": "crm", "id": "42" } }).
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.