attune/docs/webhooks/webhook-testing.md

Webhook Testing Documentation

This document describes the comprehensive test suite for the Attune webhook system, covering both Phase 2 (basic functionality) and Phase 3 (advanced security features).

Test Files

1. crates/common/tests/webhook_tests.rs

Repository-level integration tests for webhook database operations.

Coverage:

• Webhook enable/disable functionality
• Webhook key generation and uniqueness
• Webhook key regeneration
• Finding triggers by webhook key
• Idempotent webhook enabling

Key Tests:

• test_webhook_enable - Verifies webhook can be enabled and generates valid key
• test_webhook_disable - Verifies webhook can be disabled while preserving key
• test_webhook_key_regeneration - Tests key rotation functionality
• test_find_by_webhook_key - Tests lookup by webhook key
• test_webhook_key_uniqueness - Ensures unique keys across triggers
• test_enable_webhook_idempotent - Verifies enabling twice returns same key

2. crates/api/tests/webhook_api_tests.rs

API endpoint integration tests for webhook management and basic receiving.

Coverage:

• Webhook management endpoints (enable/disable/regenerate)
• Basic webhook receiving
• Authentication requirements
• Error handling for invalid keys

Key Tests:

• test_enable_webhook - Tests enabling webhooks via API
• test_disable_webhook - Tests disabling webhooks via API
• test_regenerate_webhook_key - Tests key regeneration via API
• test_receive_webhook - Tests successful webhook reception
• test_receive_webhook_invalid_key - Tests invalid key handling
• test_receive_webhook_disabled - Tests disabled webhook rejection
• test_webhook_requires_auth_for_management - Tests auth enforcement
• test_receive_webhook_minimal_payload - Tests minimal payload acceptance

3. crates/api/tests/webhook_security_tests.rs

Comprehensive security feature tests (Phase 3).

Coverage:

• HMAC signature verification (SHA256, SHA512, SHA1)
• Rate limiting
• IP whitelisting (IPv4, IPv6, CIDR)
• Payload size limits
• Event logging
• Combined security features
• Error scenarios

Test Categories

HMAC Signature Tests

test_webhook_hmac_sha256_valid

Verifies SHA256 HMAC signature validation works correctly.

• Enables HMAC with SHA256 algorithm
• Generates valid signature
• Confirms webhook is accepted (200 OK)

test_webhook_hmac_sha512_valid

Verifies SHA512 HMAC signature validation.

• Uses SHA512 algorithm
• Tests stronger hashing algorithm support

test_webhook_hmac_invalid_signature

Tests rejection of invalid signatures.

• Sends webhook with malformed signature
• Expects 401 Unauthorized response

test_webhook_hmac_missing_signature

Tests rejection when signature is required but missing.

• HMAC enabled but no signature header provided
• Expects 401 Unauthorized response

test_webhook_hmac_wrong_secret

Tests rejection when signature uses wrong secret.

• Generates signature with incorrect secret
• Expects 401 Unauthorized response

Rate Limiting Tests

test_webhook_rate_limit_enforced

Verifies rate limiting prevents excessive requests.

• Configures limit of 3 requests per 60 seconds
• Sends 3 successful requests
• 4th request returns 429 Too Many Requests

test_webhook_rate_limit_disabled

Confirms webhooks work without rate limiting.

• Sends 10 consecutive requests
• All succeed when rate limiting disabled

IP Whitelisting Tests

test_webhook_ip_whitelist_allowed

Tests IP whitelist allows configured IPs.

• Configures whitelist with CIDR and exact IP
• Tests both CIDR range match (192.168.1.100 in 192.168.1.0/24)
• Tests exact IP match (10.0.0.1)
• Both return 200 OK

test_webhook_ip_whitelist_blocked

Tests IP whitelist blocks non-whitelisted IPs.

• Sends request from IP not in whitelist (8.8.8.8)
• Expects 403 Forbidden response

Payload Size Limit Tests

test_webhook_payload_size_limit_enforced

Verifies payload size limits are enforced.

• Sets 1 KB limit
• Sends 2 KB payload
• Expects 400 Bad Request response

test_webhook_payload_size_within_limit

Tests payloads within limit are accepted.

• Sets 10 KB limit
• Sends small payload
• Expects 200 OK response

Event Logging Tests

test_webhook_event_logging_success

Verifies successful webhooks are logged.

• Sends successful webhook
• Checks log entry exists
• Validates log contains status code, IP, user agent

test_webhook_event_logging_failure

Verifies failed webhooks are logged.

• Sends failing webhook (HMAC failure)
• Checks log entry with error details
• Validates failure reason recorded

Combined Security Tests

test_webhook_all_security_features_pass

Tests webhook passing all security checks.

• Enables HMAC, rate limiting, IP whitelist, size limit
• Sends properly authenticated, allowed webhook
• Verifies all checks pass and event created
• Validates log shows all features verified

test_webhook_multiple_security_failures

Tests multiple security feature failures.

• Enables multiple features
• Sends webhook failing multiple checks
• Verifies first failure prevents further processing

Error Scenario Tests

test_webhook_malformed_json

Tests handling of malformed JSON payloads.

• Sends invalid JSON
• Expects 400 Bad Request response

test_webhook_empty_payload

Tests handling of empty payloads.

• Sends empty body
• Expects 400 Bad Request response

Running Tests

Run All Tests

cargo test --workspace

Run Specific Test Suite

# Repository tests
cargo test -p attune-common webhook_tests

# API tests
cargo test -p attune-api webhook_api_tests

# Security tests
cargo test -p attune-api webhook_security_tests

Run Ignored Tests (Requires Database)

cargo test --workspace -- --ignored

Run Specific Test

cargo test -p attune-api test_webhook_hmac_sha256_valid -- --ignored

Test Environment Setup

Tests require:

1. PostgreSQL Database - Running on localhost:5432 (or configured via DATABASE_URL)
2. Test User - Username: test_user, Password: test_password
3. Migrations Applied - All database migrations must be up to date

Setup Commands

# Set database URL
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/attune"

# Run migrations
sqlx migrate run

# Create test user (if not exists)
psql $DATABASE_URL -c "
INSERT INTO attune.identity (username, email, password_hash, enabled)
VALUES ('test_user', 'test@example.com', '$argon2id$...', true)
ON CONFLICT (username) DO NOTHING;
"

Test Coverage Summary

Feature	Test Count	Status
Basic Webhook Management	8	✅ Complete
HMAC Verification	5	✅ Complete
Rate Limiting	2	✅ Complete
IP Whitelisting	2	✅ Complete
Payload Size Limits	2	✅ Complete
Event Logging	2	✅ Complete
Combined Security	2	✅ Complete
Error Scenarios	2	✅ Complete
Total	25	✅ Complete

Security Test Matrix

HMAC	Rate Limit	IP Whitelist	Size Limit	Expected Result
✅ Valid	✅ OK	✅ Allowed	✅ OK	200 OK
❌ Invalid	N/A	N/A	N/A	401 Unauthorized
⚠️ Missing	N/A	N/A	N/A	401 Unauthorized
✅ Valid	❌ Exceeded	N/A	N/A	429 Too Many Requests
✅ Valid	✅ OK	❌ Blocked	N/A	403 Forbidden
✅ Valid	✅ OK	✅ Allowed	❌ Too Large	400 Bad Request

Known Test Limitations

1. Rate Limit Window Tests - Tests don't verify time-based window expiry (would require time manipulation)
2. Concurrent Rate Limiting - No tests for concurrent request handling
3. IPv6 Whitelist - Limited IPv6 testing coverage
4. Webhook Retry - Not yet implemented (Phase 4 feature)
5. Performance Tests - No load/stress tests included

Future Test Additions

Phase 4 Features (Planned)

• Webhook retry logic tests
• Payload transformation tests
• Multiple webhook keys per trigger
• Webhook health check tests
• Analytics and metrics tests

Additional Coverage Needed

• Concurrent webhook processing
• Database connection failure handling
• Message queue failure scenarios
• Performance benchmarks
• Security penetration testing

Debugging Failed Tests

Common Issues

Test fails with "Failed to connect to database"

# Check database is running
pg_isready -h localhost -p 5432

# Verify DATABASE_URL
echo $DATABASE_URL

# Test connection
psql $DATABASE_URL -c "SELECT 1"

Test fails with "Trigger not found"

• Ensure migrations are up to date: sqlx migrate run
• Check schema exists: psql $DATABASE_URL -c "\dn"

Test fails with "Authentication required"

• Verify test user exists in database
• Check JWT_SECRET environment variable is set

Rate limit test fails unexpectedly

• Database state may have rate limit entries from previous tests
• Clear webhook_event_log table between test runs

Manual Testing

For manual testing instructions, see webhook-manual-testing.md.

Continuous Integration

Tests are configured to run in CI/CD pipeline with:

• PostgreSQL service container
• Test database initialization
• Migration application
• Test user creation
• Parallel test execution

See .github/workflows/test.yml (if configured) for CI setup.

Test Maintenance

Adding New Tests

1. Follow existing test structure and naming conventions
2. Use test helpers (setup_test_state, create_test_pack, etc.)
3. Clean up test data after test completion
4. Mark as #[ignore] if requires external dependencies
5. Document test purpose and expected behavior
6. Add test to this documentation

Updating Tests for New Features

1. Update relevant test files
2. Add new test categories if needed
3. Update test coverage summary
4. Update security test matrix if applicable
5. Document any new test requirements

---

Last Updated: 2025-01-20
Test Suite Version: 1.0
Phase Completion: Phase 3 ✅