A secure Netlify webhook handler for processing fund application form submissions. This webhook receives form submissions from Netlify Forms, verifies their authenticity, stores the data, and sends notifications via email and Slack.

• ✅ Secure JWT Signature Verification - Validates webhook authenticity using JWT (JWS) with HMAC-SHA256
• ✅ Data Storage - Stores submissions in Val Town blob storage with deduplication
• ✅ Email Notifications - Sends formatted emails to the fund team
• ✅ Slack Integration - Posts notifications to Slack channels
• ✅ Comprehensive Error Handling - Proper HTTP status codes and error responses
• ✅ Request Logging - Detailed logging for debugging and monitoring
• ✅ Test Script - Automated testing with signature generation

The webhook implements robust security by verifying Netlify's JWT (JSON Web Signature) for every incoming request. This ensures that only authentic requests from Netlify are processed.

1. Netlify Signs the Request

   • When Netlify sends a webhook, it creates a JWT token
   • The JWT payload includes a SHA-256 hash of the request body
   • Netlify signs the JWT using your shared secret (NETLIFY_FORM_JWS)
   • The signed JWT is sent in the x-webhook-signature header

2. Webhook Verification Process

   // 1. Extract JWT from header
   const jwtToken = req.headers.get("x-webhook-signature");
   
   // 2. Calculate SHA-256 hash of request body
   const bodyHash = await crypto.subtle.digest("SHA-256", requestBody);
   
   // 3. Decode JWT header and payload (without verifying yet)
   const [headerB64, payloadB64, signatureB64] = jwtToken.split(".");
   const payload = JSON.parse(atob(payloadB64));
   
   // 4. Compare body hash with hash in JWT payload
   if (payload.sha256 !== hex(bodyHash)) {
     return 401; // Body was tampered with
   }
   
   // 5. Verify JWT signature using shared secret
   const isValid = await crypto.subtle.verify(
     { name: "HMAC", hash: "SHA-256" },
     signingKey,
     signature,
     dataToSign
   );

3. Security Guarantees

   • Authenticity: Only requests signed with your secret are accepted
   • Integrity: Any tampering with the request body is detected
   • Non-repudiation: The signature proves the request came from Netlify

# Netlify webhook signing secret (JWS)
# Find this in Netlify: Site Settings > Build & Deploy > Environment > Forms > Webhook secret
NETLIFY_FORM_JWS=your_netlify_jws_secret

# Slack webhook URL for notifications
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

The webhook expects form submissions with the following fields:

• name - Applicant's name
• email - Applicant's email address (required)
• company - Company name
• website - Company website URL
• deck - Link to pitch deck
• message - Additional message/notes

graph TD
    A[Netlify Form Submitted] --> B[Webhook Receives POST]
    B --> C[Verify Headers Present]
    C --> D[Extract JWT Token]
    D --> E[Hash Request Body SHA-256]
    E --> F[Decode JWT Payload]
    F --> G[Compare Body Hash with JWT Hash]
    G --> H[Verify JWT Signature HMAC-SHA256]
    H --> I[Check Event Type]
    I --> J[Parse Form Data]
    J --> K[Validate Required Fields]
    K --> L[Check for Duplicates]
    L --> M[Store in Blob Storage]
    M --> N[Send Email Notification]
    N --> O[Send Slack Notification]
    O --> P[Return Success Response]

• Key Format: pwv-fund-submission-{submission_id}
• Storage: Val Town blob storage (JSON format)
• Deduplication: Prevents duplicate processing of the same submission

• Recipient: dt@prestonwernerventures.com
• Subject: PWV Fund - New Submission - {company_name}
• Format: Structured text with all form fields and extracted domain

• Channel: Configured via SLACK_WEBHOOK_URL
• Format: Formatted message with submission details and edit link

POST /

{
  "id": "submission_unique_id",
  "number": 95,
  "data": {
    "name": "John Doe",
    "email": "john@example.com",
    "company": "Example Corp",
    "website": "https://example.com",
    "deck": "https://deck-link.com",
    "message": "We're building the future..."
  },
  "created_at": "2025-12-22T17:31:35.939Z",
  "site_name": "pwv-www",
  "form_name": "apply"
}

{
  "ok": true
}

{
  "ok": true
}

{
  "ok": false,
  "error": "Invalid signature"
}

The test-webhook.ts file provides an automated way to test the webhook with proper JWT signature generation:

// Run the test script
import test from "./test-webhook.ts";

What the test script does:

1. ✅ Uses real sample data from production form submissions
2. ✅ Calculates SHA-256 hash of the request body
3. ✅ Generates a valid JWT token signed with your NETLIFY_FORM_JWS secret
4. ✅ Includes all required headers (x-netlify-event, x-webhook-signature)
5. ✅ Sends POST request to the webhook endpoint
6. ✅ Displays detailed results with status, body, and pass/fail indication

Test output example:

🧪 Testing PWV Fund Application Webhook
============================================================

📤 Sending POST request to webhook endpoint...
   with x-netlify-event: submission_created
   with JWT signature in x-webhook-signature header

📥 Response received:
   Status: 200
   Body: {"ok":true}

✅ TEST PASSED: Webhook accepted the signed request

Running the test:

• Click "Run" button in the Val Town editor
• Or execute via module import in another val
• Test will automatically run when the file is loaded

Important Notes:

• The test uses the same sample submission ID each time
• Second run will detect duplicate and return early (expected behavior)
• To test multiple times, change the id field in the sample data

For manual testing, you need to generate a valid JWT signature:

# This won't work - signature needs to be properly generated
curl -X POST https://your-webhook-url.web.val.run \
  -H "Content-Type: application/json" \
  -H "x-netlify-event: submission_created" \
  -H "x-webhook-signature: <VALID_JWT_TOKEN>" \
  -d '{"id":"test","data":{...}}'

Note: Manual testing requires generating a valid JWT token. Use the test-webhook.ts script instead for accurate testing.

To test the webhook logic without signature verification during development:

1. Temporarily comment out the signature verification in main.ts
2. Send requests without the x-webhook-signature header
3. Important: Always re-enable signature verification before deploying

• Logs: All requests and errors are logged with detailed context
• Request History: Use Val Town's request history to debug issues
• Error Tracking: Comprehensive error messages for troubleshooting
• Test Script: Regular testing with test-webhook.ts to verify functionality

1. Set Environment Variables: Configure NETLIFY_FORM_JWS and SLACK_WEBHOOK_URL
2. Deploy to Val Town: The webhook is automatically deployed as an HTTP endpoint
3. Configure Netlify:
   • Navigate to Site Settings > Build & Deploy > Forms
   • Add your Val Town webhook URL
   • Generate and save the webhook secret to NETLIFY_FORM_JWS
4. Test: Run test-webhook.ts to verify the integration

• Secret Rotation: Regularly rotate the NETLIFY_FORM_JWS secret
  • Generate new secret in Netlify
  • Update environment variable in Val Town
  • Update test-webhook.ts with new secret
• HTTPS Only: Webhook only accepts HTTPS requests
• JWT Verification: All requests must have valid JWT signatures
• Body Integrity: SHA-256 hash verification prevents tampering
• Input Validation: All form data is validated before processing
• Error Handling: Sensitive information is not exposed in error messages

1. 401 Unauthorized - Invalid signature

   • Cause: JWT signature verification failed
   • Solutions:
     • Verify NETLIFY_FORM_JWS matches the secret in Netlify
     • Check that JWT token is correctly formatted
     • Ensure request body hasn't been modified
     • Run test-webhook.ts to verify your secret is correct

2. 401 Unauthorized - Body hash mismatch

   • Cause: Request body doesn't match the hash in JWT payload
   • Solutions:
     • Check for middleware modifying the request body
     • Ensure content encoding is correct
     • Verify no proxy is altering the request

3. Missing Headers

   • Cause: Required headers not present
   • Solutions:
     • Ensure Netlify is configured to send webhooks
     • Check webhook configuration in Netlify settings
     • Verify event type is "submission_created"

4. 500 Errors

   • Cause: Missing environment variables
   • Solutions:
     • Verify NETLIFY_FORM_JWS is set
     • Verify SLACK_WEBHOOK_URL is set
     • Check Val Town environment variables

5. Email/Slack Failures

   • Cause: Service configuration issues
   • Solutions:
     • Check respective service configurations
     • Verify credentials and permissions
     • Review service logs for specific errors

1. Check Val Town request logs for detailed error information
2. Run the test script (test-webhook.ts) to isolate issues
3. Verify JWT signature using online JWT decoder (jwt.io)
4. Compare hashes - decode JWT and check if SHA-256 hash matches body
5. Test with minimal payload to isolate issues
6. Verify environment variables are properly set
7. Check Netlify webhook settings for correct URL and secret

Use this checklist to debug JWT verification problems:

• JWT token is present in x-webhook-signature header
• JWT has three parts separated by dots (header.payload.signature)
• JWT payload contains sha256 field
• Request body hash matches sha256 in JWT payload
• NETLIFY_FORM_JWS environment variable is set correctly
• Secret matches the one configured in Netlify
• JWT signature algorithm is HS256 (HMAC-SHA256)

• main.ts - Main webhook handler with JWT verification
• test-webhook.ts - Automated test script with JWT signing
• README.md - This documentation

This project is part of Preston-Werner Ventures' internal tooling.