Sep 7

Option for Static Webhook Secret or Raw Payload Support

**Summary** It is currently difficult to reliably verify SavvyCal webhook signatures when using certain frameworks. Since the HMAC signature is generated from the *exact raw request payload*, if only the parsed JSON is available, the signature cannot be reproduced. This makes proper verification impossible in those environments. --- ### Problem * Signature verification requires the **raw string** of the request body. * Many frameworks parse the JSON body before user code can access it. * Once parsed, the original raw string (with its exact whitespace, key ordering, and encoding) is lost. * Attempting to `JSON.stringify` the parsed body is unreliable and does not consistently match the string SavvyCal used. * As a result, webhook authenticity cannot be guaranteed in these setups. --- ### Why This Matters * Security: Without reliable verification, webhook endpoints are vulnerable to spoofed requests. * Developer Experience: Many developers integrating with SavvyCal don’t have low-level access to the raw request body. This creates friction and prevents secure usage. --- ### Suggested Solutions #### 1. **Static Secret Verification (Preferred)** Provide an option for webhooks to include a static, pre-shared secret header (e.g., `x-savvycal-secret`) instead of an HMAC over the body. * This is simpler to implement in environments without raw-body access. * Security is still strong, provided HTTPS is used and the secret is sufficiently random. * Many webhook providers offer this as a fallback option for exactly this reason (e.g., Slack’s `signing secret` vs GitHub’s `secret`). #### 2. **Dual Signature Headers** Include both: * The existing `x-savvycal-signature` (HMAC of raw body). * An optional `x-savvycal-secret` (static). This would keep backward compatibility while giving developers flexibility. #### 3. **Optional Canonical JSON Serialization** If sticking with HMAC verification only, provide a guarantee that the body is always serialized using a canonical JSON format (no whitespace differences, predictable key ordering, UTF-8 encoding). * This would allow developers to `JSON.stringify` the parsed object and reliably match your HMAC. * While less flexible, it makes signature verification feasible without needing raw-body access. --- ### Benefits * Broader compatibility with modern frameworks and headless CMS platforms. * Easier onboarding for developers integrating webhooks. * Improved security posture, since more teams would be able to verify webhooks correctly instead of skipping verification.

Pending