Configure and Validate Webhook HMAC Signature Secrets
The portal webhook infrastructure validates all inbound Dynamics webhook payloads using HMAC signature verification before enqueuing them for processing. The global administrator must configure the shared secret that the Dynamics portal signs its payloads with. This configuration is stored securely outside the main application database and injected into the Supabase Edge Function environment. The global admin can rotate the secret when required and trigger a validation test to confirm that a sample payload verifies correctly against the newly configured secret.
User Story
Acceptance Criteria
- Given a global admin navigates to the webhook configuration section, when they enter a new HMAC secret and save, then the Edge Function immediately uses the new secret for all subsequent payload verification
- Given the HMAC secret is configured, when a global admin triggers the validation test, then the system sends a sample signed payload to the webhook endpoint and reports whether verification succeeded or failed
- Given the HMAC secret is not configured, when the webhook endpoint receives an inbound payload, then it rejects the payload with a 401 response and logs the rejection
- Given a global admin rotates the HMAC secret, when payloads signed with the old secret arrive during the rotation window, then those payloads are rejected and a rotation warning is logged
- Given the HMAC secret configuration form, when a global admin views it, then the current secret value is masked and only the last 4 characters are visible for confirmation purposes
Business Value
The webhook endpoint is a publicly accessible network boundary accepting external data that will be written into the Supabase database. Without HMAC signature validation, any actor with knowledge of the endpoint URL could inject arbitrary membership updates, course enrollment changes, or other sync events, potentially corrupting organizational data across all user accounts. Signature validation is a non-negotiable security control for this integration boundary.
Components
- Portal Webhook Infrastructure infrastructure
- Portal Integration Repository data