Add webhooks API endpoints

[i7an]

Motivation

Document public Webhooks API endpoints

Changes

• Added full CRUD documentation for the webhooks API

Summary by CodeRabbit

• New Features
  • Webhook management API now available for creating, configuring, listing, retrieving, updating, and deleting webhook endpoints to handle event notifications.

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request adds comprehensive webhook management functionality to the email-sending API specification. Five new REST endpoints enable creating, retrieving, updating, and deleting webhook configurations, along with related request/response schemas and parameter definitions.

Changes

Cohort / File(s)	Summary
Webhook API Specification specs/email-sending.openapi.yml	Added five webhook management endpoints (POST, GET, PATCH, DELETE) with CRUD operations, new Webhook and WebhookCreateResponse schemas, webhook configuration fields (url, webhook_type, payload_format, event_types, etc.), and webhook_id path parameter. Includes signing secret generation on creation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• MT-20455: Remove webhooks spec #14 — Consolidates webhook API specification by removing the separate specs/webhooks.openapi.yml file in parallel with these webhook endpoint additions.

Suggested reviewers

• IgorDobryn
• VladimirTaytor
• leonid-shevtsov

Poem

🐰 Webhooks bloom in OpenAPI gardens bright,
Five new endpoints dancing left and right,
Create, read, patch, delete with signing keys,
The webhook symphony flows with ease! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The pull request description is minimal and lacks required sections from the template. It's missing 'How to test' section with test cases and 'Images and GIFs' section.	Add the 'How to test' section with specific test cases for the CRUD operations, and consider adding 'Images and GIFs' comparisons if applicable for documentation changes.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Add webhooks API endpoints' directly and concisely summarizes the main change: introducing new webhook management REST endpoints to the OpenAPI specification.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch add-webhooks-api-spec

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (3)

specs/email-sending.openapi.yml (3)

1471-1490: Consider 201 Created for resource creation.

createWebhook returns 200 on success. Idiomatically a POST that creates a resource returns 201 Created. I see the existing createSendingDomain also uses 200, 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 on sending_stream / event_types are only documented, not enforced.

The description states that sending_stream and event_types are required for email_sending webhooks, but the schema only lists url and webhook_type in required. This is acceptable documentation-wise, but consider splitting the request body into a oneOf over webhook_type (email_sending vs audit_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 for listWebhooks.

listWebhooks returns 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 with listEmailLogs) 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

📥 Commits

Reviewing files that changed from the base of the PR and between 8cbe777 and 176cea0.

📒 Files selected for processing (1)

• specs/email-sending.openapi.yml

[i7an]

keep flat (but TBD later)

Do we have a final decision? :)