Webhook Destinations

Configure outbound webhooks so Gnosari pushes collected and updated data to your own systems in real time, instead of you polling the API.

---

Overview

A webhook destination is a URL you register with Gnosari. Whenever a selected event happens (new data collected, or previously collected data updated), Gnosari sends a signed POST request to that URL with the event payload.

Every destination has:

• A URL: where the request is sent
• Event kinds: which events trigger a delivery (Data collected, Data updated)
• An active state: inactive destinations keep their history but receive no new deliveries
• A conversation-provenance opt-in: off by default (see Include Conversation Provenance)
• A signing secret: used to verify a delivery genuinely came from Gnosari
• A delivery log: every attempt, including retries and failures

---

Accessing Webhook Destinations

1. Click your profile picture in the top-right corner
2. Select Settings
3. Click Webhooks in the settings sidebar

Or go directly to: /settings/webhooks

---

Adding a Destination

1. Navigate to Settings → Webhooks
2. Click Add destination (top-right)
3. Enter the Destination URL, the endpoint Gnosari will POST to
4. Select one or more Events
5. (Optional) Enable Include conversation provenance
6. Click Add destination

New destinations are active immediately (there is no "active" toggle at creation time, every new destination starts active).

Destination URL Requirements

• Must be a reachable http(s) URL
• Internal/link-local addresses are refused: Gnosari blocks requests to internal network ranges (e.g. 169.254.169.254) as an SSRF guard

If the server refuses a URL, the exact reason is shown in the create/edit dialog, for example:

Blocked destination: 169.254.169.254 resolves to the internal address 169.254.169.254

Choosing Events

Event	Fires when
Data collected	The first time Gnosari collects a new piece of data in a conversation
Data updated	Previously collected data is updated

At least one event is required. The form blocks submission otherwise.

---

Editing a Destination

Two ways to edit:

• From the list: click the pencil icon on a destination's row (opens an edit dialog)
• From the detail page: click a destination's URL to open /settings/webhooks/{id}, edit the fields directly, then click Save changes

The edit form additionally exposes an Active switch (not present when creating), so you can deactivate a destination without deleting it.

---

Activating / Deactivating

Toggle the switch next to a destination (list view) or in the header of its detail page.

State	Behavior
Active	Receives new deliveries for its selected events
Inactive	Keeps its full delivery history; receives no new deliveries until reactivated

---

Deleting a Destination

1. Click the trash icon next to the destination (list row, or the detail page header)
2. Confirm the deletion in the dialog

Warning: Deleting a destination is permanent and removes it from the list immediately. Its past delivery history is not retained after deletion.

---

Include Conversation Provenance

A per-destination opt-in, off by default, on both the create and edit forms.

When enabled: deliveries to that destination include verbatim conversation quotes and message references showing exactly where each piece of collected data came from.

When disabled (default): deliveries carry the collected data only, without quoting the underlying conversation.

Only enable this for destinations that are allowed to store conversation content. The quoted text may include anything a user said during the conversation.

---

Signing Secret

Every destination has a signing secret used to verify that a delivery genuinely came from Gnosari, not an impersonator.

Viewing the Secret

1. Open a destination's detail page: /settings/webhooks/{id}
2. Scroll to Signing secret
3. Click Reveal secret

The secret is masked by default and is only fetched from the server when you click Reveal. It is never loaded or cached ahead of time. Click Hide secret to mask it again, or Copy to copy the revealed value to your clipboard.

Verifying a Delivery

Each delivery request carries a webhook-signature header. Compute an HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw request body} using your signing secret, and compare it to the header value to confirm the request is authentic and unmodified.

---

Delivery Log

The bottom of each destination's detail page (/settings/webhooks/{id}) shows its delivery history: every attempt Gnosari made to reach that destination.

Columns

Column	Description
Time	When the attempt occurred
Event	Which event kind triggered it
Outcome	Delivered or Failed
Reason	Why a failed attempt failed (blank for successful deliveries)
Attempt	The retry number for that delivery
HTTP status	The status code your endpoint returned, if any

Filtering

Use the All attempts / Delivered / Failed filter (top-right of the log) to narrow the view.

Retry Groups

When a delivery is retried, its attempts are grouped together under a Retry group header showing the event kind and the number of attempts (e.g. 9×). The newest attempt in a group is listed first.

Failure Reasons

Reason	Meaning
DNS failure	The destination hostname could not be resolved
TLS failure	The secure connection to the destination failed
Connect timeout	The destination did not accept the connection in time
Read timeout	The destination connected but did not respond in time
HTTP status	The destination responded with an error status
SSRF refused	The destination address is not allowed

An unrecognized failure reason from the server is shown as-is rather than hidden.

---

Troubleshooting

"The destination could not be created" / "...updated"

Cause: The server rejected the request without a specific reason (e.g. a transient error).

Solutions:

• Try again in a moment
• Verify the URL is reachable and not on an internal network range

Destination shows repeated failed deliveries

Cause: Your endpoint is unreachable, timing out, or returning a non-2xx status.

Solutions:

1. Open the destination's delivery log and check the Reason and HTTP status columns for the specific failure
2. Confirm your endpoint is up and responding within a reasonable time
3. Deactivate the destination temporarily while you fix the endpoint. This stops new delivery attempts without losing history

"This destination does not exist or belongs to another account"

Cause: The destination was deleted, or the link points to a destination on a different account.

Solution: Return to Settings → Webhooks and select a destination from your current account's list.

---

Next Steps

• Manage your API keys for programmatic access alongside webhooks
• See the Gnosari API and MCP documentation for the webhook event payload contract and signature verification details

---

Last updated: 2026-08-11