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:

Manual testing

Test webhook endpoints manually:

Last updated