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 registration

Manual 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);
"