Add webhook signature verification for inbound integrations

[Oluwaseyi89]

Summary

Add webhook signature verification for inbound integrations — /api/v1/webhooks/stellar and /api/v1/webhooks/soroban accept unauthenticated POST bodies and write them straight into TransactionConfirmation/dispatch, letting any external party forge transaction confirmations.

Social Media Link

Let's collaborate on Discord. And ensure to star our repo.

Problem Statement

Confirmed in corporate-platform/corporate-platform-backend/src/webhooks/webhooks.controller.ts, corporate-platform/corporate-platform-backend/src/webhooks/services/stellar-webhook.service.ts, and corporate-platform/corporate-platform-backend/src/webhooks/dto/stellar-webhook.dto.ts:

1. No guard on the delivery endpoints: registerWebhook, listWebhooks, and unregisterWebhook are protected with @UseGuards(JwtAuthGuard, RolesGuard) + @Roles('admin'), but receiveStellarWebhook (POST /stellar) and receiveSorobanEvent (POST /soroban) have no guards at all.

2. No signature header verification: neither StellarWebhookDto nor receiveStellarWebhook/receiveSorobanEvent check any X-Signature, X-Hub-Signature-256, or equivalent HMAC header before processing the payload.

3. Body is trusted and persisted directly: StellarWebhookService.registerTransaction() takes dto straight from the unauthenticated request and upserts it into transactionConfirmation, so a forged POST can create or overwrite a transaction's recorded status, ledgerSequence, and metadata.

4. receiveSorobanEvent accepts any: the DTO type is any, so the payload is dispatched to WebhookDispatcherService.dispatch() with zero schema validation in addition to zero signature check.

5. upsert allows silent overwrite of existing confirmations: a forged webhook for an existing transactionHash can flip a real pending/failed transaction to CONFIRMED (or vice versa) since registerTransaction always upserts on transactionHash with no ownership check.

6. No replay protection: even a legitimately-signed webhook, once captured, could be resent indefinitely — there is no nonce, timestamp window, or delivery-id dedup on the inbound side (distinct from WebhookDispatcherService's outbound delivery tracking).

7. No source IP or allowlist check: nothing restricts these endpoints to Stellar/Soroban infrastructure's known origins as a defense-in-depth measure.

8. No rate limiting on the public routes: receiveStellarWebhook and receiveSorobanEvent have no throttle guard, so they are also open to flooding.

9. Failure to verify has no audit trail: there is no SecurityService.logEvent call recording rejected/suspicious webhook deliveries, so an active forgery attempt would leave no security signal.

10. companyId is client-supplied and trusted: StellarWebhookDto.companyId comes directly from the unauthenticated body and is persisted onto transactionConfirmation.companyId with no verification that the transaction actually belongs to that company.

Required Changes

1. Add an HMAC-based signature verification guard (e.g. WebhookSignatureGuard) applied to receiveStellarWebhook and receiveSorobanEvent, validating a shared-secret signature header against the raw request body.

2. Store the webhook signing secret in ConfigService/environment configuration, separate from JWT_SECRET and STELLAR_SECRET_KEY.

3. Reject requests with a missing or invalid signature with 401 Unauthorized before any DTO validation or persistence occurs.

4. Replace the any type on receiveSorobanEvent's body with a validated DTO class.

5. Add a timestamp or nonce field to the expected payload and reject requests outside an acceptable time window (e.g. 5 minutes) to prevent replay.

6. Change StellarWebhookService.registerTransaction() to reject (not silently upsert) updates to a transactionHash whose existing companyId differs from the payload's companyId.

7. Derive companyId from a verified server-side mapping (e.g. registered webhook source) instead of trusting the client-supplied field where possible.

8. Add rate limiting to both public webhook routes consistent with the rest of the API's rate-limiting strategy.

9. Log rejected/invalid webhook deliveries via SecurityService.logEvent with signature-failure details (excluding the secret itself).

10. Add unit and integration tests covering: valid signature accepted, missing signature rejected, invalid signature rejected, and replayed timestamp rejected.

Acceptance Criteria

1. POST /api/v1/webhooks/stellar rejects requests without a valid signature header.
2. POST /api/v1/webhooks/soroban rejects requests without a valid signature header.
3. receiveSorobanEvent payloads are validated against a typed DTO, not any.
4. A forged webhook payload cannot overwrite an existing transactionConfirmation for a different company.
5. Replayed (stale-timestamp) webhook deliveries are rejected.
6. Rejected webhook attempts are recorded via SecurityService.logEvent.
7. Legitimate signed webhooks from the real Stellar/Soroban integration continue to be processed without behavior change.
8. Rate limiting is applied to both public webhook endpoints.
9. Unit tests cover valid, missing, invalid, and replayed signature scenarios.
10. Webhook signing secret is documented and distinct from other application secrets.

Directory to Work on:

corporate-platform/corporate-platform-backend/

[akandeisaac021-design]

@akandeisaac021-design has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi there, I'd like to contribute to this.

I'll implement this following the existing conventions in the codebase, with tests covering the new behavior.

Looking forward to contributing — please assign this issue to me.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @akandeisaac021-design to this issue.

[odarome132]

@odarome132 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hello maintainer, I'd love to contribute. Please assign

ℹ️ Repo Maintainers: To accept this application, review their application or assign @odarome132 to this issue.

[pharwasz]

@pharwasz has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Can I hop on this issue, will get it done as soon as possible with good accuracy

ℹ️ Repo Maintainers: To accept this application, review their application or assign @pharwasz to this issue.

[rajiabdulrahmon2020-ui]

@rajiabdulrahmon2020-ui has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I’ve reviewed the issue and have a solid understanding of what needs to be addressed. I’d like to take responsibility for the implementation and ensure the resulting changes are reliable, well-tested, and easy to maintain.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @rajiabdulrahmon2020-ui to this issue.

[drips-wave]

Congratulations, @rajiabdulrahmon2020-ui! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @rajiabdulrahmon2020-ui: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[rajiabdulrahmon2020-ui]

@rajiabdulrahmon2020-ui Implemented and opened rajiabdulrahmon2020-ui#1. Inbound webhooks now require timestamped HMAC signatures, typed Soroban payloads, replay/rate-limit protection, security audit logging, and company ownership checks.

[rajiabdulrahmon2020-ui]

@rajiabdulrahmon2020-ui Correction: the implementation is now submitted to the upstream repository at #607, using the fork branch only as the PR head. This is the canonical PR for review and issue closure.

[drips-wave]

This issue has been completed by @rajiabdulrahmon2020-ui as part of the Stellar Wave Program's 8th Wave 🥳

😎 @rajiabdulrahmon2020-ui: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.