attune/docs/webhooks/webhook-manual-testing.md

Webhook System Manual Testing Guide

Last Updated: 2026-01-20
Status: Phase 2 Complete

This guide provides step-by-step instructions for manually testing the webhook system functionality.

---

Prerequisites

1. Attune API service running (default: http://localhost:8080)
2. Database with migrations applied
3. Test user account registered
4. curl or similar HTTP client
5. jq for JSON formatting (optional)

---

Setup Test Environment

1. Start the API Service

cd crates/api
cargo run

2. Register a Test User (if not already registered)

curl -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "webhook_test_user",
    "email": "webhook@example.com",
    "password": "test_password_123"
  }'

3. Login and Get JWT Token

TOKEN=$(curl -s -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "webhook_test_user",
    "password": "test_password_123"
  }' | jq -r '.data.access_token')

echo "Token: $TOKEN"

---

Test Scenario 1: Enable Webhooks for Existing Trigger

Step 1: Create a Test Pack

curl -X POST http://localhost:8080/api/v1/packs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "webhook_test",
    "label": "Webhook Test Pack",
    "description": "Pack for webhook testing",
    "version": "1.0.0",
    "enabled": true
  }' | jq

Step 2: Create a Test Trigger

curl -X POST http://localhost:8080/api/v1/triggers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "webhook_test.github_push",
    "pack_ref": "webhook_test",
    "label": "GitHub Push Event",
    "description": "Trigger for GitHub push webhooks",
    "enabled": true,
    "param_schema": {
      "type": "object",
      "properties": {
        "repository": {"type": "string"},
        "branch": {"type": "string"}
      }
    }
  }' | jq

Step 3: Enable Webhooks

curl -X POST http://localhost:8080/api/v1/triggers/webhook_test.github_push/webhooks/enable \
  -H "Authorization: Bearer $TOKEN" | jq

Expected Response:

{
  "data": {
    "id": 1,
    "ref": "webhook_test.github_push",
    "label": "GitHub Push Event",
    "webhook_enabled": true,
    "webhook_key": "wh_abc123...xyz789",
    ...
  }
}

Verify:

• webhook_enabled is true
• webhook_key starts with wh_
• webhook_key is 40+ characters long

Step 4: Save Webhook Key

WEBHOOK_KEY=$(curl -s -X GET http://localhost:8080/api/v1/triggers/webhook_test.github_push \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data.webhook_key')

echo "Webhook Key: $WEBHOOK_KEY"

---

Test Scenario 2: Send Webhook Events

Step 1: Send a Basic Webhook

curl -X POST http://localhost:8080/api/v1/webhooks/$WEBHOOK_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "repository": "attune/automation-platform",
      "branch": "main",
      "commits": [
        {
          "sha": "abc123",
          "message": "Add webhook support",
          "author": "developer@example.com"
        }
      ]
    }
  }' | jq

Expected Response:

{
  "data": {
    "event_id": 1,
    "trigger_ref": "webhook_test.github_push",
    "received_at": "2026-01-20T15:30:00Z",
    "message": "Webhook received successfully"
  }
}

Verify:

• Response status is 200 OK
• event_id is a positive integer
• trigger_ref matches the trigger
• received_at is a valid ISO timestamp

Step 2: Send Webhook with Metadata

curl -X POST http://localhost:8080/api/v1/webhooks/$WEBHOOK_KEY \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: push" \
  -H "X-GitHub-Delivery: abc-123-def-456" \
  -d '{
    "payload": {
      "action": "synchronize",
      "number": 42,
      "pull_request": {
        "title": "Add new feature",
        "state": "open"
      }
    },
    "headers": {
      "X-GitHub-Event": "push",
      "X-GitHub-Delivery": "abc-123-def-456"
    },
    "source_ip": "192.30.252.1",
    "user_agent": "GitHub-Hookshot/abc123"
  }' | jq

Verify:

• Event created successfully
• Metadata is stored in event config

Step 3: Verify Event Was Created

curl -X GET http://localhost:8080/api/v1/events \
  -H "Authorization: Bearer $TOKEN" | jq

Expected: Events list includes the webhook-triggered events

---

Test Scenario 3: Webhook Key Management

Step 1: Regenerate Webhook Key

curl -X POST http://localhost:8080/api/v1/triggers/webhook_test.github_push/webhooks/regenerate \
  -H "Authorization: Bearer $TOKEN" | jq

Expected Response:

{
  "data": {
    "webhook_enabled": true,
    "webhook_key": "wh_new_key_different_from_old",
    ...
  }
}

Verify:

• New webhook_key is different from the old one
• Still starts with wh_

Step 2: Verify Old Key No Longer Works

# Try to use the old webhook key (should fail)
curl -X POST http://localhost:8080/api/v1/webhooks/$WEBHOOK_KEY \
  -H "Content-Type: application/json" \
  -d '{"payload": {"test": "data"}}' | jq

Expected: 404 Not Found - "Invalid webhook key"

Step 3: Get New Key and Test

NEW_WEBHOOK_KEY=$(curl -s -X GET http://localhost:8080/api/v1/triggers/webhook_test.github_push \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data.webhook_key')

curl -X POST http://localhost:8080/api/v1/webhooks/$NEW_WEBHOOK_KEY \
  -H "Content-Type: application/json" \
  -d '{"payload": {"test": "with new key"}}' | jq

Expected: 200 OK - Event created successfully

---

Test Scenario 4: Disable Webhooks

Step 1: Disable Webhooks

curl -X POST http://localhost:8080/api/v1/triggers/webhook_test.github_push/webhooks/disable \
  -H "Authorization: Bearer $TOKEN" | jq

Expected Response:

{
  "data": {
    "webhook_enabled": false,
    "webhook_key": null,
    ...
  }
}

Verify:

• webhook_enabled is false
• webhook_key is null

Step 2: Verify Webhook No Longer Accepts Events

curl -X POST http://localhost:8080/api/v1/webhooks/$NEW_WEBHOOK_KEY \
  -H "Content-Type: application/json" \
  -d '{"payload": {"test": "should fail"}}' | jq

Expected: 404 Not Found - "Invalid webhook key"

---

Test Scenario 5: Error Handling

Test 1: Invalid Webhook Key

curl -X POST http://localhost:8080/api/v1/webhooks/wh_invalid_key_xyz \
  -H "Content-Type: application/json" \
  -d '{"payload": {}}' | jq

Expected: 404 Not Found

Test 2: Regenerate Without Enabling First

# Create new trigger without webhooks
curl -X POST http://localhost:8080/api/v1/triggers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "webhook_test.no_webhook",
    "pack_ref": "webhook_test",
    "label": "No Webhook Trigger",
    "enabled": true
  }' | jq

# Try to regenerate without enabling
curl -X POST http://localhost:8080/api/v1/triggers/webhook_test.no_webhook/webhooks/regenerate \
  -H "Authorization: Bearer $TOKEN" | jq

Expected: 400 Bad Request - "Webhooks are not enabled for this trigger"

Test 3: Management Endpoints Without Auth

curl -X POST http://localhost:8080/api/v1/triggers/webhook_test.github_push/webhooks/enable | jq

Expected: 401 Unauthorized

---

Test Scenario 6: Integration with Rules

Step 1: Create a Rule for Webhook Trigger

# First, create a test action
curl -X POST http://localhost:8080/api/v1/actions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "webhook_test.log_event",
    "pack_ref": "webhook_test",
    "label": "Log Webhook Event",
    "description": "Logs webhook events",
    "entrypoint": "echo \"Webhook received: {{event.payload}}\"",
    "runtime_ref": "shell",
    "enabled": true
  }' | jq

# Create rule
curl -X POST http://localhost:8080/api/v1/rules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "webhook_test.on_github_push",
    "pack_ref": "webhook_test",
    "label": "On GitHub Push",
    "description": "Execute action when GitHub push webhook received",
    "trigger_ref": "webhook_test.github_push",
    "action_ref": "webhook_test.log_event",
    "enabled": true
  }' | jq

Step 2: Re-enable Webhooks

curl -X POST http://localhost:8080/api/v1/triggers/webhook_test.github_push/webhooks/enable \
  -H "Authorization: Bearer $TOKEN" | jq

WEBHOOK_KEY=$(curl -s -X GET http://localhost:8080/api/v1/triggers/webhook_test.github_push \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data.webhook_key')

Step 3: Send Webhook and Verify Rule Execution

# Send webhook
curl -X POST http://localhost:8080/api/v1/webhooks/$WEBHOOK_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "repository": "test/repo",
      "branch": "main"
    }
  }' | jq

# Wait a moment for processing, then check executions
sleep 2

curl -X GET http://localhost:8080/api/v1/executions \
  -H "Authorization: Bearer $TOKEN" | jq

Expected: Execution created for the webhook_test.log_event action

---

Verification Checklist

Webhook Enablement

• Can enable webhooks for a trigger
• Webhook key is generated and returned
• Webhook key format is correct (starts with wh_)
• webhook_enabled field is true

Webhook Receiver

• Can send webhook with basic payload
• Can send webhook with metadata
• Event is created in database
• Event has webhook metadata in config
• Response includes event ID and trigger reference

Webhook Management

• Can regenerate webhook key
• Old key stops working after regeneration
• New key works immediately
• Can disable webhooks
• Disabled webhooks return 404

Error Handling

• Invalid webhook key returns 404
• Regenerate without enabling returns 400
• Management endpoints require authentication
• Disabled trigger webhooks return 404

Integration

• Webhook creates event
• Event triggers rule evaluation
• Rule creates execution
• Execution runs action

---

Cleanup

# Delete test rule
curl -X DELETE http://localhost:8080/api/v1/rules/webhook_test.on_github_push \
  -H "Authorization: Bearer $TOKEN"

# Delete test action
curl -X DELETE http://localhost:8080/api/v1/actions/webhook_test.log_event \
  -H "Authorization: Bearer $TOKEN"

# Delete test triggers
curl -X DELETE http://localhost:8080/api/v1/triggers/webhook_test.github_push \
  -H "Authorization: Bearer $TOKEN"

curl -X DELETE http://localhost:8080/api/v1/triggers/webhook_test.no_webhook \
  -H "Authorization: Bearer $TOKEN"

# Delete test pack
curl -X DELETE http://localhost:8080/api/v1/packs/webhook_test \
  -H "Authorization: Bearer $TOKEN"

---

Troubleshooting

Webhook Key Not Generated

• Verify database migration applied
• Check API logs for errors
• Ensure trigger exists before enabling webhooks

Webhook Not Creating Event

• Verify webhook key is correct
• Check that trigger has webhook_enabled = true
• Ensure payload is valid JSON
• Check API logs for errors

Rule Not Executing

• Verify rule is enabled
• Check that rule's trigger matches webhook trigger
• Review executor service logs
• Ensure worker service is running

---

Next Steps

After verifying Phase 2 functionality:

1. Implement Phase 3 features (HMAC, rate limiting)
2. Build Web UI for webhook management
3. Add webhook event history and analytics
4. Create example packs using webhooks (GitHub, Stripe, etc.)