Skip to main content
Before integrating webhooks, make sure you’ve completed the Quickstart guide and have your authentication set up.

Overview

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:
  • Poll the API endpoints periodically (not recommended for production)
  • Use webhooks to receive real-time event updates (recommended)

Webhooks vs Polling

  • Make repeated GET requests to check transaction status - Higher latency and more resource intensive - May miss state changes between polls - Better suited for testing/debugging
  • Receive instant notifications when state changes - More efficient and scalable - No missed events - Recommended for production use

Setting Up Webhooks

1. Create Your Webhook URL

Create a POST endpoint on your server to receive webhook events. The endpoint should:
  1. Accept JSON payloads
  2. Return a 200 OK response
  3. Process events idempotently (handle duplicates safely)

2. Register Your Webhook URL

Add your webhook URL to your account settings:
Request
Response

Security

Security Notice

Important Security Considerations:
  • Never expose sensitive credentials in client-side code or VCS
  • Always validate request signatures and origins
  • Use HTTPS for all API communications
  • Implement proper access control and authentication
  • Follow secure key management practices
Never Share or Expose:
  • API Keys
  • Secret Keys
  • Encryption Keys
  • Webhook Secrets
  • Authentication Tokens
Key Security Measures:
  1. Store sensitive data in secure environment variables or dedicated key management systems
  2. Implement IP whitelisting where possible
  3. Validate all incoming webhook signatures
  4. Use strong TLS/SSL for all connections
  5. Rotate credentials regularly
  6. Log and monitor access attempts
  7. Follow the principle of least privilege
Implementation Tips:
For additional security best practices, refer to our Security Guidelines in the documentation.

Verifying Webhook Origins

Secure your webhook endpoint using either or both:

1. Checksum Validation

Each webhook includes a checksum for verification:
To validate:
  1. Concatenate: event|json_encoded_data
  2. Create HMAC SHA-256 hash using your business ID as the key
  3. Compare with the received checksum
The encoded data must exclude the checksum field and be in alphabetical order:
Valid Order

2. IP Whitelisting

Whitelist these Juicyway IPs:

Go-Live Checklist

1

Verify Public Access

Ensure your webhook URL is publicly accessible (no localhost)
2

URL Configuration

Add trailing / if using .htaccess
3

Test Integration

Verify JSON parsing and 200 OK responses
4

Handle Long Tasks

Return 200 OK before processing lengthy operations
5

Monitor Failed Webhooks

Track non-200 responses in your logs
6

Implement Idempotency

Handle duplicate events safely

Supported Events

In sandbox, successful transactions remain pending. Only failure events are sent.

Payment Events

Next Steps