feat(dev-portal-web): DOMA-12705 add webhooks documentation… #7052
Conversation
…e ts-schema Added comprehensive webhooks documentation for invoices in both English and Russian, including webhook setup, signature verification, retry policy, and best practices.
AleX83Xpert
added
the
✋🙂 Review please
WalkthroughThis PR adds comprehensive webhook documentation for invoice-related features in English and Russian, updates invoice documentation metadata to include webhook navigation entries, and extends the GraphQL schema with development and production app URL fields for B2BApp entities with filtering and sorting support. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10–15 minutes
Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (3)
apps/dev-portal-web/gql/index.ts (1)
4722-4744: Consider exposing new URL fields in B2B app fragments/queries if neededThe
B2BAppFragmentand thecreateB2BApp/updateB2BAppoperations still only selectdeveloperUrland export IDs; they don’t includedevelopmentAppUrl/productionAppUrl. If the UI needs to display or immediately re-use these URLs after create/update, you may want to extend the fragment and related queries to select them as well. If they’re only used server‑side, the current selection is fine.Also applies to: 5094-5132
apps/dev-portal-web/docs/api/examples/invoices/webhooks.ru.mdx (2)
133-143: Consider adding input validation.The signature verification function could benefit from explicit validation of required parameters to prevent runtime errors and provide clearer error messages.
function verifyWebhookSignature(rawBody, signature, secret, algorithm) { + // Validate inputs + if (!rawBody || !signature || !secret || !algorithm) { + return false + } + const allowedAlgorithms = new Set(['sha256', 'sha384', 'sha512']) if (!allowedAlgorithms.has(algorithm)) return false const expectedSignature = crypto .createHmac(algorithm, secret) .update(rawBody) .digest('hex') return signature === expectedSignature }
146-166: Add error handling for robustness.The middleware example lacks error handling for several failure scenarios: missing headers, JSON parsing errors, and failed secret retrieval. Adding these checks would make the example more production-ready.
app.post('/webhook/payment', express.text({ type: 'application/json' }), (req, res) => { const signature = req.headers['x-webhook-signature'] const algorithm = req.headers['x-webhook-signature-algorithm'] || 'sha256' const webhookId = req.headers['x-webhook-id'] const rawBody = req.body + // Validate required headers + if (!signature || !webhookId) { + return res.status(400).json({ error: 'Missing required headers' }) + } + // Получаем сохраненный секрет для этого счета const secret = getStoredSecretForInvoice(invoiceId) + + if (!secret) { + return res.status(500).json({ error: 'Failed to retrieve secret' }) + } if (!verifyWebhookSignature(rawBody, signature, secret, algorithm)) { return res.status(401).json({ error: 'Invalid signature' }) } + let payload + try { - const payload = JSON.parse(rawBody) + payload = JSON.parse(rawBody) + } catch (error) { + return res.status(400).json({ error: 'Invalid JSON payload' }) + } // Обрабатываем вебхук console.log(`Статус платежа ${payload.id} изменен на ${payload.status}`) res.status(200).json({ status: 'ok' }) })
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
apps/dev-portal-web/docs/api/examples/invoices/_meta.en.json(1 hunks)apps/dev-portal-web/docs/api/examples/invoices/_meta.ru.json(1 hunks)apps/dev-portal-web/docs/api/examples/invoices/webhooks.en.mdx(1 hunks)apps/dev-portal-web/docs/api/examples/invoices/webhooks.ru.mdx(1 hunks)apps/dev-portal-web/gql/index.ts(14 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-06-25T07:34:53.845Z
Learnt from: YEgorLu
Repo: open-condo-software/condo PR: 6308
File: apps/condo/schema.graphql:2333-2333
Timestamp: 2025-06-25T07:34:53.845Z
Learning: In GraphQL schemas, update input types should typically have all fields optional to support partial updates. This allows clients to only provide the fields they want to change rather than being forced to provide all fields.
Applied to files:
apps/dev-portal-web/gql/index.ts
🧬 Code graph analysis (1)
apps/dev-portal-web/gql/index.ts (1)
apps/condo/schema.ts (2)
InputMaybe(5-5)Scalars(12-24)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: Build open-source part (ubuntu-22.04, 24.x, 3.14)
- GitHub Check: Lint source code (24.x)
- GitHub Check: Semgrep vulnerabilities check
- GitHub Check: Check dependencies integrity (24.x)
🔇 Additional comments (14)
apps/dev-portal-web/docs/api/examples/invoices/_meta.en.json (1)
4-5: LGTM!The navigation metadata update correctly adds the new webhooks documentation entry with proper JSON formatting.
apps/dev-portal-web/docs/api/examples/invoices/webhooks.en.mdx (9)
1-22: LGTM!The introduction, workflow steps, and field documentation are clear, well-organized, and provide a solid foundation for understanding webhook functionality.
24-70: LGTM!The GraphQL mutation example and response are well-structured and demonstrate the correct usage of webhook fields. The security warning about storing the secret is an important reminder for developers.
72-100: LGTM!The webhook payload example is comprehensive and clearly demonstrates the structure developers will receive, including nested organization and invoice objects.
102-110: LGTM!The payment statuses are clearly documented with meaningful descriptions for each state.
112-121: LGTM!The webhook headers are well-documented with clear descriptions and supported algorithm values.
168-174: LGTM!The URL whitelist requirement is clearly communicated with a clear call to action for registration.
176-182: LGTM!The best practices section provides solid, security-focused guidance covering all critical aspects of webhook implementation.
184-200: LGTM!The retry policy is clearly documented with a reasonable exponential backoff schedule and explicit time limits.
202-208: LGTM!The error handling guidance provides clear HTTP status code recommendations and explains which codes trigger retries.
apps/dev-portal-web/gql/index.ts (3)
53-73: B2B app URL fields on create/update/history inputs are consistent and optional
developmentAppUrl/productionAppUrlare added across B2B create/update/history inputs asInputMaybe<String>, matching existing patterns and keeping all update fields optional, which aligns with the partial‑update convention for input types. No issues from a schema/TS typing perspective.
Based on learnings, update inputs remain fully optional.Also applies to: 75-99, 106-129, 377-397
131-362: URL filter operators mirror existing patternsThe new
developmentAppUrl*andproductionAppUrl*filters inB2BAppHistoryRecordWhereInputandB2BAppWhereInputreplicate the full operator set used fordeveloperUrl(plain, contains, contains_i, starts_with, ends_with, not_*, *_in, etc.), so filtering capabilities are consistent and predictable. No schema/TS issues spotted here.Also applies to: 399-624
2889-2959: Sort enums extended correctly for new URL fields
SortB2BAppHistoryRecordsByandSortB2BAppsBynow includeDevelopmentAppUrlAsc/DescandProductionAppUrlAsc/Desc, aligned with the new fields and existing naming convention for sort keys. Enum values follow the same<field>_ASC/DESCpattern as the rest.apps/dev-portal-web/docs/api/examples/invoices/_meta.ru.json (1)
2-5: New Russian meta entry for webhooks looks goodThe
"webhooks": "Вебхуки"entry is correctly added, keeps the JSON valid, and is consistent with existing labels.
|
…and update ts-schema
Added comprehensive webhooks documentation for invoices in both English and Russian, including webhook setup, signature verification, retry policy, and best practices.
Summary by CodeRabbit
Documentation
New Features
✏️ Tip: You can customize this high-level summary in your review settings.