# Troubleshooting

## Common issues & solutions

### Webhook not triggered

**Possible Causes:**

* Webhook is disabled (`isEnabled: false`)
* Invalid webhook URL or unreachable endpoint
* Shop doesn't have webhook functionality enabled

**Solutions:**

* Check webhook status via GET `/webhooks/:id`
* Verify endpoint URL is accessible and returns 2xx status
* Ensure shop has webhook functionality enabled

### HMAC verification failed

**Possible Causes:**

* Using wrong secret key
* Modifying request body before verification
* Incorrect hash calculation method

**Solutions:**

* Verify secret key from Joy app settings
* Use raw request body for HMAC calculation
* Ensure using HMAC-SHA256 with base64 encoding

### Timeout issues

**Possible Causes:**

* Webhook endpoint taking too long to respond (>5 seconds)
* Network connectivity issues
* Blocking operations in webhook handler

**Solutions:**

* Implement async processing with immediate response
* Optimize webhook handler performance
* Add request timeout handling

## Testing & development

### Webhook testing tools

Use tools like ngrok for local testing:

```bash
# Install ngrok
npm install -g ngrok

# Start your local server
node webhook-server.js

# Create secure tunnel
ngrok http 3000

# Use the HTTPS URL for webhook registration
```

### Manual testing

Test webhook endpoints manually:

```bash
# Test endpoint availability
curl -X POST "https://your-server.com/webhook/test" \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

# Verify HMAC calculation
node -e "
const crypto = require('crypto');
const body = '{\"test\": \"data\"}';
const secret = 'your-secret-key';
const hmac = crypto.createHmac('sha256', secret).update(body).digest('base64');
console.log('HMAC:', hmac);
"
```