docs(flaky-tests): document webhook event schemas with field descriptions by samgutentag · Pull Request #548 · trunk-io/docs

samgutentag · 2026-04-14T10:58:31Z

Summary

Documents the three Flaky Tests webhook event types now published to Svix: test_case.monitor_status_changed, v2.test_case.status_changed, and test_case.investigation_completed
Adds field-level reference tables showing each payload field, type, and description
Updates the Supported Events section of the Flaky Tests webhooks page

Source

trunk2 PR: https://github.com/trunk-io/trunk2/pull/3519

Test plan

Preview in GitBook

…ions PR #3519 added descriptive metadata to the three Flaky Tests webhook event schemas published via Svix. Each event type now has per-field descriptions visible in the Svix app portal. Add reference tables for test_case.monitor_status_changed, v2.test_case.status_changed, and test_case.investigation_completed to the Flaky Tests webhooks page. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

trunk-staging-io · 2026-04-14T10:58:34Z

😎 Merged successfully - details.

…a-descriptions

claude · 2026-05-05T18:33:43Z

Claude finished @samgutentag's task in 1m 17s —— View job

Review complete

Gather context and read changed files
Check CLAUDE.md for repo guidelines
Review documentation for typos, grammar, formatting, and best practices
Post inline review comments
Finalize review summary

The documentation adds clear, well-structured reference tables for all three Flaky Tests webhook event types. Overall it's a solid addition. I left 5 inline comments covering the following issues — all are minor and non-blocking:

Issue	Lines	Severity
Missing comma after "e.g."	28, 44, 71	Minor (style)
Awkward sentence structure — dangling modifier	44	Minor (grammar)
Type notation inconsistency (`string[]` vs `array`)	38	Minor (consistency)
`triggered_by.monitor_id` typed as `string` vs `string (UUID)` elsewhere	52	Minor (consistency)

No blocking issues — documentation is accurate, complete, and well-organized. ✅

claude · 2026-05-05T18:34:44Z

+| `type` | string | Always `test_case.monitor_status_changed` |
+| `timestamp` | string (ISO 8601) | When the event occurred |
+| `monitor.id` | string (UUID) | Unique identifier for the monitor |
+| `monitor.type` | string | The type of monitor (e.g. `pass_on_retry`) |


claude · 2026-05-05T18:34:49Z

+
+#### `v2.test_case.status_changed`
+
+Emitted when a test case changes status (e.g. becomes flaky or is resolved), triggered by a monitor.


Two issues:

Missing comma after "e.g."

The trailing "triggered by a monitor" reads as an awkward dangling modifier. Consider rephrasing for clarity.

Suggested change

Emitted when a test case changes status (e.g. becomes flaky or is resolved), triggered by a monitor.

Emitted when a test case changes status (e.g., becomes flaky or is resolved), as triggered by a monitor.

claude · 2026-05-05T18:34:56Z

+| `test_case.classname` | string | Test classname |
+| `test_case.file_path` | string | File path of the test |
+| `test_case.html_url` | string | URL to the test detail page in Trunk |
+| `test_case.codeowners` | string[] | Code owners associated with the test |


Type notation inconsistency: string[] here but array is used for the facts field (line 70). Pick one convention and apply it consistently throughout the tables.

Suggested change

| `test_case.codeowners` | string[] | Code owners associated with the test |

| `test_case.codeowners` | array of strings | Code owners associated with the test |

claude · 2026-05-05T18:35:01Z

+| `timestamp` | string (ISO 8601) | When the event occurred |
+| `previous_status` | string | The prior status of the test case |
+| `new_status` | string | The updated status of the test case |
+| `triggered_by.monitor_id` | string | Unique identifier of the triggering monitor |


The monitor.id field in the first table is typed as string (UUID), but this analogous ID field is just string. If it's always a UUID, use string (UUID) for consistency.

Suggested change

| `triggered_by.monitor_id` | string | Unique identifier of the triggering monitor |

| `triggered_by.monitor_id` | string (UUID) | Unique identifier of the triggering monitor |

claude · 2026-05-05T18:35:05Z

+| `markdown_summary` | string | Markdown-formatted summary of findings and recommendations |
+| `failure_message` | string | The original failure message that triggered the investigation |
+| `facts` | array | Facts discovered during the investigation |
+| `facts[].fact_type` | string | Category of the fact (e.g. `GIT_BLAME`) |


github-actions

Auto-approved: Claude code review passed.

samgutentag · 2026-05-06T03:47:44Z

Triage status (2026-05-05): up to date with main. Needs review before merge.

…a-descriptions

claude · 2026-05-06T22:07:31Z

Claude finished @samgutentag's task in 1m 17s —— View job

Review complete

Read the changed file and check current state
Compare with previous review feedback to see what's been addressed
Review for typos, grammar, formatting, and best practices
Post inline comments for any new issues
Finalize review summary

This synchronize event was a merge from main — the documentation content itself is unchanged since the previous review on 2026-05-05. None of the previously identified issues have been addressed yet, so I've re-posted the same five inline suggestions on the latest commit so they're easy to find and apply:

Issue	Lines	Severity
Missing comma after "e.g."	28, 44, 71	Minor (style)
Awkward "triggered by a monitor" dangling modifier	44	Minor (grammar)
Type notation inconsistency (`string[]` vs `array`)	38	Minor (consistency)
`triggered_by.monitor_id` typed as `string` vs `string (UUID)` elsewhere	52	Minor (consistency)

All findings are minor style/consistency nits — no blocking issues. The documentation itself is accurate, complete, and well-organized.

Apply all suggestions →
· Branch

claude · 2026-05-06T22:08:33Z

+| `type` | string | Always `test_case.monitor_status_changed` |
+| `timestamp` | string (ISO 8601) | When the event occurred |
+| `monitor.id` | string (UUID) | Unique identifier for the monitor |
+| `monitor.type` | string | The type of monitor (e.g. `pass_on_retry`) |


claude · 2026-05-06T22:08:35Z

+| `test_case.classname` | string | Test classname |
+| `test_case.file_path` | string | File path of the test |
+| `test_case.html_url` | string | URL to the test detail page in Trunk |
+| `test_case.codeowners` | string[] | Code owners associated with the test |


Type notation inconsistency: string[] here, but array is used for the facts field (line 70). Pick one convention and apply it consistently throughout the tables.

Suggested change

| `test_case.codeowners` | string[] | Code owners associated with the test |

| `test_case.codeowners` | array of strings | Code owners associated with the test |

claude · 2026-05-06T22:08:37Z

+
+#### `v2.test_case.status_changed`
+
+Emitted when a test case changes status (e.g. becomes flaky or is resolved), triggered by a monitor.


Two issues:

Missing comma after "e.g."

The trailing "triggered by a monitor" reads as a dangling modifier. Consider rephrasing for clarity.

Suggested change

Emitted when a test case changes status (e.g. becomes flaky or is resolved), triggered by a monitor.

Emitted when a test case changes status (e.g., becomes flaky or is resolved), as triggered by a monitor.

claude · 2026-05-06T22:08:40Z

+| `timestamp` | string (ISO 8601) | When the event occurred |
+| `previous_status` | string | The prior status of the test case |
+| `new_status` | string | The updated status of the test case |
+| `triggered_by.monitor_id` | string | Unique identifier of the triggering monitor |


The monitor.id field in the first table is typed as string (UUID), but this analogous ID field is just string. If it's always a UUID, use string (UUID) for consistency.

Suggested change

| `triggered_by.monitor_id` | string | Unique identifier of the triggering monitor |

| `triggered_by.monitor_id` | string (UUID) | Unique identifier of the triggering monitor |

claude · 2026-05-06T22:08:41Z

+| `markdown_summary` | string | Markdown-formatted summary of findings and recommendations |
+| `failure_message` | string | The original failure message that triggered the investigation |
+| `facts` | array | Facts discovered during the investigation |
+| `facts[].fact_type` | string | Category of the fact (e.g. `GIT_BLAME`) |


github-actions

Auto-approved: Claude code review passed.

samgutentag · 2026-05-06T22:11:09Z

Verification status (2026-05-07, re-verified): live

Verified: customers can use this. Ready to publish.

Eng PR: trunk2#3519 ("feat: add descriptions to Svix webhook event schemas", merged 2026-04-14, merge commit still on main)
Linear ticket: none referenced
Flag: none (webhook events are a published API surface, not flag-gated)
Signals: schema description PR is intact on main. No rollout to chase.

Review nits applied in commit e8578e5:

Comma after "e.g." on lines 28, 44, and 71 (style)
Line 38: string[] to array of strings for consistency with the prose-form types used throughout the file
Line 44: rephrased to "Emitted when a test case changes status (e.g., becomes flaky or is resolved), as triggered by a monitor." Removes the dangling modifier
Line 52: triggered_by.monitor_id retyped from string to string (UUID) for consistency with monitor.id, repository.id, test_case.id, and investigation_id elsewhere in the same file. Confirmed by the example payload in the eng PR diff which emits a UUID

trunk check clean on the edited file.

Suggested next action: flip out of draft and merge.

Five small consistency and grammar fixes flagged by the Claude review bot on 2026-04-14 and re-flagged on 2026-05-06. None blocking, all applied verbatim to the bot's suggestion or with a minor adjustment. * Add comma after "e.g." on lines 28, 44, and 71 (style) * Line 38: change `string[]` to `array of strings` for consistency with the prose-form types used elsewhere in the file (line 70 uses `array`, parenthetical qualifiers used throughout) * Line 44: rephrase to "Emitted when a test case changes status (e.g., becomes flaky or is resolved), as triggered by a monitor." Removes the dangling modifier. * Line 52: change `triggered_by.monitor_id` type from `string` to `string (UUID)` for consistency with `monitor.id`, `repository.id`, `test_case.id`, and `investigation_id` elsewhere in the same file. Confirmed by inspection of the eng PR's example payload, which emits a UUID. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

claude · 2026-05-07T07:54:06Z

Claude finished @samgutentag's task in 36s —— View job

Review complete

Read the current state of flaky-tests/webhooks/README.md
Verify previous review nits have been addressed in e8578e5
Re-review for any remaining typos, grammar, or formatting issues
Finalize review summary

All five previously-flagged nits are resolved in e8578e5:

Issue	Line	Status
Comma after "e.g." (`pass_on_retry`)	28	✅ Fixed
`string[]` → `array of strings` consistency	38	✅ Fixed
Dangling modifier + comma on status_changed description	44	✅ Fixed
`triggered_by.monitor_id` typed as `string (UUID)`	52	✅ Fixed
Comma after "e.g." (`GIT_BLAME`)	71	✅ Fixed

I re-read the file end-to-end for any remaining typos, grammar issues, or formatting inconsistencies and found none. Type notation is consistent across all three tables (string, string (UUID), string (ISO 8601), array of strings, array, boolean, number, object), table structure is uniform, and the prose is clear.

No blocking issues. Documentation is accurate, complete, and ready to merge. ✅
· Branch

claude · 2026-05-07T07:55:21Z

Claude finished @samgutentag's task in 1m 7s —— View job

Review complete

Read current state of flaky-tests/webhooks/README.md
Verify all previously flagged nits are addressed
Re-read end-to-end for any new issues
Finalize review summary

All five previously flagged review nits are resolved at e8578e5:

Issue	Line	Status
Comma after "e.g." (`pass_on_retry`)	28	✅ Fixed
`string[]` → `array of strings` consistency	38	✅ Fixed
Dangling modifier + comma on `v2.test_case.status_changed` description	44	✅ Fixed
`triggered_by.monitor_id` typed as `string (UUID)`	52	✅ Fixed
Comma after "e.g." (`GIT_BLAME`)	71	✅ Fixed

Re-read the file end-to-end for any remaining typos, grammar issues, or formatting inconsistencies — none found. Type notation is uniform across all three tables (string, string (UUID), string (ISO 8601), array of strings, array, boolean, number, object), table headers/structure are consistent, and the prose is clear.

No blocking issues. Documentation is accurate, complete, and ready to merge. ✅
· Branch

github-actions

Auto-approved: Claude code review passed.

Merge branch 'main' into sam-gutentag/flaky-tests-webhook-event-schem…

94d7abe

…a-descriptions

claude Bot reviewed May 5, 2026

View reviewed changes

github-actions Bot approved these changes May 5, 2026

View reviewed changes

Merge branch 'main' into sam-gutentag/flaky-tests-webhook-event-schem…

898e304

…a-descriptions

claude Bot reviewed May 6, 2026

View reviewed changes

github-actions Bot approved these changes May 6, 2026

View reviewed changes

samgutentag marked this pull request as ready for review May 7, 2026 07:54

trunk-staging-io Bot merged commit 1955448 into main May 7, 2026
7 of 8 checks passed

trunk-staging-io Bot deleted the sam-gutentag/flaky-tests-webhook-event-schema-descriptions branch May 7, 2026 07:55

github-actions Bot approved these changes May 7, 2026

View reviewed changes

	\| `monitor.type` \| string \| The type of monitor (e.g. `pass_on_retry`) \|
	\| `monitor.type` \| string \| The type of monitor (e.g., `pass_on_retry`) \|


		#### `v2.test_case.status_changed`

		Emitted when a test case changes status (e.g. becomes flaky or is resolved), triggered by a monitor.

	\| `test_case.codeowners` \| string[] \| Code owners associated with the test \|
	\| `test_case.codeowners` \| array of strings \| Code owners associated with the test \|

	\| `triggered_by.monitor_id` \| string \| Unique identifier of the triggering monitor \|
	\| `triggered_by.monitor_id` \| string (UUID) \| Unique identifier of the triggering monitor \|

	\| `facts[].fact_type` \| string \| Category of the fact (e.g. `GIT_BLAME`) \|
	\| `facts[].fact_type` \| string \| Category of the fact (e.g., `GIT_BLAME`) \|

Conversation

samgutentag commented Apr 14, 2026

Summary

Source

Test plan

Uh oh!

trunk-staging-io Bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review complete

Uh oh!

claude Bot May 5, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot May 5, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot May 5, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot May 5, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot May 5, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

samgutentag commented May 6, 2026

Uh oh!

claude Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review complete

Uh oh!

claude Bot May 6, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot May 6, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot May 6, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot May 6, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot May 6, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

samgutentag commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude Bot commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review complete

Uh oh!

claude Bot commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review complete

Uh oh!

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

trunk-staging-io Bot commented Apr 14, 2026 •

edited

Loading

claude Bot commented May 5, 2026 •

edited

Loading

claude Bot commented May 6, 2026 •

edited

Loading

samgutentag commented May 6, 2026 •

edited

Loading

claude Bot commented May 7, 2026 •

edited

Loading

claude Bot commented May 7, 2026 •

edited

Loading