Feature/issue 547 idempotent webhook

[Tekprecious]

Description

This pull request implements issue #547 by introducing a new secure, asynchronous, and idempotent webhook endpoint to receive verification results from the external AI service. This is a critical piece of infrastructure that decouples the main application from the AI processing, improving system resilience and scalability by allowing for reliable, out-of-band communication.

All acceptance criteria have been met:

• HMAC Signature Verification: The endpoint is protected by an HmacAuthGuard that validates the X-Signature-256 header.
• Idempotency: The service checks for a unique eventId in the new WebhookEvent table before processing to prevent duplicate updates from repeated deliveries.
• Safe Error Envelopes: The endpoint returns standard HTTP status codes (401 for bad signatures, 409 for duplicates, 404 for missing sessions) to provide clear feedback to the calling service.

Implementation Details

1. New WebhooksModule: A dedicated module (WebhooksModule, WebhooksController, WebhooksService) has been created to handle all incoming webhooks. This encapsulates the logic for the new POST /webhooks/ai-verification endpoint.

2. HMAC Signature Verification: A new HmacAuthGuard secures the endpoint. It computes a SHA256 HMAC of the raw request body using a shared secret (AI_WEBHOOK_SECRET) and compares it in a time-safe manner to the signature provided in the X-Signature-256 header.

3. Idempotency Layer: The WebhooksService now performs an idempotency check using the eventId from the payload. It queries a new WebhookEvent table in the database to see if an event has already been processed. If it has, the service immediately returns a 409 Conflict status to acknowledge receipt without reprocessing.

4. Prisma Schema Update: A new WebhookEvent model was added to prisma/schema.prisma to store a record of each processed webhook, which is the foundation for the idempotency check.

5. Integration with SessionService: Upon successful validation, the WebhooksService finds the correct identity_verification step within the specified session and calls sessionService.submitToStep to update the session's state with the AI's results. The entire operation is wrapped in a database transaction to ensure atomicity.

6. Configuration & Middleware:

   • The AI_WEBHOOK_SECRET has been added to the application's configuration service.
   • The main application bootstrap (main.ts) has been updated to enable rawBody parsing for JSON requests, which is a prerequisite for the HMAC guard to function correctly.

7. Unit Tests: Comprehensive unit tests have been added for WebhooksController and WebhooksService to cover success paths, error handling (duplicate events, missing sessions), and integration with service mocks.

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update

Testing

• Added unit tests for WebhooksController and WebhooksService.
• Manually tested the endpoint with a mock client, verifying success (200), invalid signature (401), and duplicate event (409) responses.
• Verified that rawBody is correctly parsed and available to the guard.
• Confirmed that a new record is created in the webhook_events table upon successful processing.

Related Issues

Closes #547

[vercel]

@whitezaddy is attempting to deploy a commit to the Cedarich's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@Tekprecious Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Cedarich]

@Tekprecious

[Tekprecious]

@Tekprecious

Noted

[Tekprecious]

@Cedarich Authorize vercel

[Cedarich]

Fix conflict @Tekprecious

[Tekprecious]

Fix conflict @Tekprecious

done