Skip to content

docs(modules): precision follow-up — event-transaction scope, payload sensitivity (HT-71) #84

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zaridan merged 1 commit into from
Jul 19, 2026
Merged

docs(modules): precision follow-up — event-transaction scope, payload sensitivity (HT-71) #84

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/modules/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ credentials and different capabilities.

| Surface | What it does | Guide |
|---|---|---|
| **Typed events** | The engine records eight kinds of domain event (a new conversation, inbound mail, a status change, a resolved draft, …) reliably, in the same transaction as the change they describe. | [webhooks.md](./webhooks.md) |
| **Typed events** | The engine records eight kinds of domain event (a new conversation, inbound mail, a status change, a resolved draft, …) reliably — each written in the same database transaction as the state change it describes, so a rolled-back change never emits and a committed one never silently drops its event. (The synthetic `test.ping` is the one exception: it exercises the delivery path directly and never touches the outbox.) | [webhooks.md](./webhooks.md) |
| **Webhook delivery** | Registered HTTPS endpoints receive signed, at-least-once notifications of those events. | [webhooks.md](./webhooks.md) |
| **Assistant actors** | AI principals that authenticate with a bearer token, read conversations through the same read API Agents use, and post draft replies that a human Agent must approve before anything is sent. | [assistants-and-drafts.md](./assistants-and-drafts.md) |

Expand Down
7 changes: 5 additions & 2 deletions docs/modules/webhooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,8 +122,11 @@ delivered as a non-test event:
**Events are thin by design.** `data` carries only identifiers and small
typed facts — never a message body, subject line, or address. Fetch full
content through the read API (`GET /api/v1/conversations/{id}`) with your
own credentials once an event tells you something changed. This keeps every
webhook payload free of customer content and PII by construction.
own credentials once an event tells you something changed. Message content
therefore never transits a webhook — but treat payloads as sensitive
anyway: some fields are operator-authored free text (`conversation.tags_changed`
carries the tag strings themselves), and identifiers still reveal that a
given conversation exists and is active.
Comment on lines +125 to +129

@coderabbitai coderabbitai Bot Jul 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Avoid implying every identified conversation is active.

A webhook can reference conversations in closed, pending, or spam states, so the identifier alone establishes existence, not that the conversation is active.

Proposed wording 
- and identifiers still reveal that a
- given conversation exists and is active.
+ and identifiers still reveal that a given conversation exists; some event
+ types may also expose its current status.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
own credentials once an event tells you something changed. Message content
therefore never transits a webhook — but treat payloads as sensitive
anyway: some fields are operator-authored free text (`conversation.tags_changed`
carries the tag strings themselves), and identifiers still reveal that a
given conversation exists and is active.
own credentials once an event tells you something changed. Message content
therefore never transits a webhook — but treat payloads as sensitive
anyway: some fields are operator-authored free text (`conversation.tags_changed`
carries the tag strings themselves), and identifiers still reveal that a given conversation exists; some event
types may also expose its current status.
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/modules/webhooks.md` around lines 125 - 129, Update the webhook
sensitivity guidance in the surrounding documentation to state that identifiers
reveal a conversation exists, without implying it is active. Preserve the
warning about sensitive payloads and operator-authored free text, and account
for conversations in closed, pending, or spam states.


**Soft-deleted conversations fire nothing.** Deletion is invisible on every
other endpoint (a `404`, indistinguishable from never having existed) and
Expand Down
Loading