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:
# 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 registrationManual testing
Test webhook endpoints manually:
# 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);
"