# Troubleshooting

## Common Issues

### Webhook Not Found (404)

**Symptom:**

```
HTTP/1.1 404 Not Found
```

**Causes & Solutions:**

1. **Incorrect URL path**

   ```bash
   # Wrong: Missing prefix
   curl http://localhost:8080/my-webhook

   # Correct: Include full path
   curl http://localhost:8080/webhooks/v1alpha2/my-webhook
   ```
2. **Configuration mismatch**

   ```yaml
   # Configuration
   entrypointUrl: /github/events

   # URL should be:
   /webhooks/v1alpha2/github/events
   ```

### Authentication Failed (401)

**Symptom:**

```json
{
  "error": "security validation failed"
}
```

**Solutions:**

1. **Check secret/token**

   ```bash
   # Verify environment variable is set
   echo $WEBHOOK_SECRET

   # Ensure it matches configuration
   export WEBHOOK_SECRET="correct-secret"
   ```
2. **Check headers**

   ```bash
   # Missing required header
   curl -H "X-API-Key: key" ...
   ```

### Rate Limit Exceeded (429)

**Symptom:**

```json
{
  "error": "rate limit exceeded",
  "client_ip": "192.168.1.100"
}
```

**Solutions:**

1. **Increase limits**

   ```yaml
   throttling:
     maxRequests: 10000  # Increase
     window: 60
   ```
2. **Add burst capacity**

   ```yaml
   throttling:
     burst: 100
     burstWindow: 10
   ```

### Storage Connection Failed

**Symptom:**

```
Error: storage failed: connection refused
```

**Solutions:**

1. **Check connectivity**

   ```bash
   # Test Redis
   redis-cli -h localhost ping
   ```
2. **Verify credentials**

   ```yaml
   storage:
     - type: redis
       specs:
         host: localhost  # Correct host
         port: 6379      # Correct port
         password:       # Correct password
           valueFrom:
             envRef: REDIS_PASSWORD
   ```

### Template Errors

**Symptom:**

```
Error: template parsing failed
```

**Solutions:**

1. **Check syntax**

   ```yaml
   # Wrong: Missing closing brace
   templateString: '{{ .Value }'

   # Correct
   templateString: '{{ .Value }}'
   ```
2. **Handle nil values**

   ```yaml
   templateString: |
     {{ with .Data }}
       {{ .Field | default "N/A" }}
     {{ end }}
   ```
3. **Validate JSON**

   ```yaml
   templateString: |
     {{ if .Payload }}
       {{ with $data := fromJSON .Payload }}
         {{ $data.field }}
       {{ end }}
     {{ end }}
   ```

## Debugging Techniques

#### Enable Debug Logging

```bash
export WH_DEBUG=true
./webhooked serve --config webhooked.yaml
```

#### Check Configuration

```bash
# Validate configuration
./webhooked --validate --config webhooked.yaml
```

#### Monitor Metrics

```bash
# Check metrics endpoint
curl http://localhost:8080/metrics | grep webhooked

# Key metrics to watch
webhooked_http_requests_total
webhooked_storage_errors_total
webhooked_security_rejections_total
```

#### Test Individual Components

```bash
# Test webhook endpoint
curl -i -X POST http://localhost:8080/webhooks/v1alpha2/test \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

# Test health endpoint
curl http://localhost:8080/health

# Test readiness
curl http://localhost:8080/ready
```

## Error Messages

| Error                            | Meaning                | Solution                |
| -------------------------------- | ---------------------- | ----------------------- |
| `spec not found`                 | Webhook not configured | Check configuration     |
| `security validation failed`     | Auth failed            | Check credentials       |
| `rate limit exceeded`            | Too many requests      | Wait or increase limits |
| `connection refused`             | Storage down           | Check storage service   |
| `context deadline exceeded`      | Timeout                | Check storage service   |
| `invalid template`               | Template error         | Fix template syntax     |
| `environment variable not found` | Missing env var        | Export variable         |

## FAQ

<details>

<summary><strong>Q: Why am I getting 404 errors?</strong></summary>

A: Check that your URL includes `/webhooks/v1alpha2/` prefix.

</details>

<details>

<summary><strong>Q: How do I increase request limits?</strong></summary>

&#x20;A: Adjust `throttling.maxRequests` in configuration.

</details>

<details>

<summary><strong>Q: Can I disable authentication for testing?</strong> </summary>

A: Yes, use `security.type: noop` (never in production).

</details>

<details>

<summary><strong>Q: How do I debug template errors?</strong> </summary>

A: Enable debug mode with `WH_DEBUG=true`.

</details>

<details>

<summary><strong>Q: Why is storage failing?</strong> </summary>

A: Check connectivity, credentials, and firewall rules.

</details>

## Getting Help

1. **Check logs**: Enable debug logging
2. **Review configuration**: Validate YAML syntax
3. **Test components**: Isolate the issue
4. **GitHub Issues**: Report bugs
5. **Community**: Ask questions

***

*Most issues can be resolved by checking configuration and connectivity.*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.atom.codes/webhooked/introduction/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.