Conversation
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughAdds a new "webhooks" tag and a set of CRUD webhook management endpoints to the email-sending OpenAPI spec, plus a required ChangesWebhook API Specification
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
i7an
force-pushed
the
add-webhooks-api-spec
branch
from
6a88f3a to
2fd22a9
Compare
i7an
force-pushed
the
add-webhooks-api-spec
branch
from
2fd22a9 to
176cea0
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (3)
specs/email-sending.openapi.yml (3)
1471-1490: Consider201 Createdfor resource creation.
createWebhookreturns200on success. Idiomatically a POST that creates a resource returns201 Created. I see the existingcreateSendingDomainalso uses200, so this matches the codebase convention — flagging only in case you'd like to correct both or keep the inconsistency intentional.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@specs/email-sending.openapi.yml` around lines 1471 - 1490, The OpenAPI response for the POST endpoint that creates a webhook (createWebhook) currently uses HTTP 200; change the response code to 201 Created and update the description to "Webhook created successfully" (or similar) to reflect resource creation; ensure the response schema ($ref: '#/components/schemas/WebhookCreateResponse') and example remain unchanged, and consider applying the same change to createSendingDomain for consistency if you decide to align conventions across the spec.
1402-1470: Conditional requirements onsending_stream/event_typesare only documented, not enforced.The description states that
sending_streamandevent_typesare required foremail_sendingwebhooks, but the schema only listsurlandwebhook_typeinrequired. This is acceptable documentation-wise, but consider splitting the request body into aoneOfoverwebhook_type(email_sendingvsaudit_log) with a discriminator so the contract is machine-enforceable and codegen produces correct types.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@specs/email-sending.openapi.yml` around lines 1402 - 1470, Split the current webhook object schema into a oneOf with two concrete schemas (e.g., EmailSendingWebhook and AuditLogWebhook) and add a discriminator on webhook_type so tooling can pick the correct variant; the EmailSendingWebhook schema should require url, webhook_type, sending_stream, and event_types and keep their properties/enum definitions, while the AuditLogWebhook schema should require only url and webhook_type and reuse shared properties (active, payload_format, domain_id) as appropriate; update the parent property named webhook to reference the oneOf and remove the conditional text-only requirement so the contract is machine-enforceable and codegen emits correct types.
1498-1544: Consider pagination forlistWebhooks.
listWebhooksreturns all webhooks without any pagination parameters. If an account can have many webhook configurations, this may grow unbounded over time. Consider adding cursor- or page-based pagination (consistent withlistEmailLogs) or documenting the server-side limit.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@specs/email-sending.openapi.yml` around lines 1498 - 1544, The listWebhooks operation currently returns all webhooks unpaginated; update the OpenAPI spec for operationId listWebhooks to support pagination by adding either page-based parameters (e.g., page, per_page) or cursor-based parameters (e.g., after, limit) consistent with listEmailLogs, update the 200 response schema to include a paginated wrapper (data + meta or next_cursor) and adjust the example accordingly, and/or document a server-side maximum limit if you prefer to keep a single response; ensure parameter names and response schema keys match existing pagination conventions used elsewhere in the spec.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@specs/email-sending.openapi.yml`:
- Around line 1471-1490: The OpenAPI response for the POST endpoint that creates
a webhook (createWebhook) currently uses HTTP 200; change the response code to
201 Created and update the description to "Webhook created successfully" (or
similar) to reflect resource creation; ensure the response schema ($ref:
'#/components/schemas/WebhookCreateResponse') and example remain unchanged, and
consider applying the same change to createSendingDomain for consistency if you
decide to align conventions across the spec.
- Around line 1402-1470: Split the current webhook object schema into a oneOf
with two concrete schemas (e.g., EmailSendingWebhook and AuditLogWebhook) and
add a discriminator on webhook_type so tooling can pick the correct variant; the
EmailSendingWebhook schema should require url, webhook_type, sending_stream, and
event_types and keep their properties/enum definitions, while the
AuditLogWebhook schema should require only url and webhook_type and reuse shared
properties (active, payload_format, domain_id) as appropriate; update the parent
property named webhook to reference the oneOf and remove the conditional
text-only requirement so the contract is machine-enforceable and codegen emits
correct types.
- Around line 1498-1544: The listWebhooks operation currently returns all
webhooks unpaginated; update the OpenAPI spec for operationId listWebhooks to
support pagination by adding either page-based parameters (e.g., page, per_page)
or cursor-based parameters (e.g., after, limit) consistent with listEmailLogs,
update the 200 response schema to include a paginated wrapper (data + meta or
next_cursor) and adjust the example accordingly, and/or document a server-side
maximum limit if you prefer to keep a single response; ensure parameter names
and response schema keys match existing pagination conventions used elsewhere in
the spec.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: d2e20676-0f75-420e-b934-7df11d4b6ce9
📒 Files selected for processing (1)
specs/email-sending.openapi.yml
i7an
commented
Apr 17, 2026
| -H 'Authorization: Bearer YOUR_API_KEY' \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "webhook": { |
Contributor
Author
There was a problem hiding this comment.
keep flat (but TBD later)
Do we have a final decision? :)
IgorDobryn
approved these changes
Apr 20, 2026
Ma-Anna
approved these changes
May 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
Document public Webhooks API endpoints
Changes
Summary by CodeRabbit