Integration Guide for Webhook Events
Before integrating webhooks, make sure you’ve completed the Quickstart guide and have your authentication set up.
When you make a request to our API, you’ll typically get an immediate response. However, some operations like payments can take time to process. Instead of timing out, we return a pending status and use webhooks to notify you of the final result.
You have two options for handling these async operations:
Polling Approach
Webhook Approach
Create a POST endpoint on your server to receive webhook events. The endpoint should:
Add your webhook URL to your account settings:
Important Security Considerations:
Detailed Security Guidelines
Never Share or Expose:
Key Security Measures:
Implementation Tips:
For additional security best practices, refer to our Security Guidelines in the documentation.
Secure your webhook endpoint using either or both:
Each webhook includes a checksum for verification:
To validate:
event|json_encoded_data
(data must be alphabetically sorted)The encoded data must exclude the checksum field and be in alphabetical order:
Whitelist these Juicyway IPs:
Verify Public Access
Ensure your webhook URL is publicly accessible (no localhost)
URL Configuration
/
if using .htaccessTest Integration
Handle Long Tasks
Return 200 OK before processing lengthy operations
Monitor Failed Webhooks
Track non-200 responses in your logs
Implement Idempotency
In sandbox, successful transactions remain pending. Only failure events are sent.
payment.session.failed|succeeded