Webhooks

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

Setting Up Webhooks

1. Create Your Webhook URL

Create a POST endpoint on your server to receive webhook events. The endpoint should:

Accept JSON payloads
Return a 200 OK response
Process events idempotently (handle duplicates safely)

from flask import Flask, request
import hmac
import hashlib
import json

app = Flask(__name__)

def validate_signature(payload, checksum, business_id):
  # Separate event and data
  event = payload['event']
  data = payload['data']

  # Sort data alphabetically and encode
  sorted_data = json.dumps(data, sort_keys=True)
  message = f"{event}|{sorted_data}"

  # Create HMAC SHA256 hash
  expected = hmac.new(
    business_id.encode('utf-8'),
    message.encode('utf-8'),
    hashlib.sha256
  ).hexdigest().upper()

  return hmac.compare_digest(expected, checksum)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
  payload = request.json
  checksum = payload.get('checksum')
  business_id = 'YOUR_BUSINESS_ID'

  # Validate webhook signature
  if not validate_signature(payload, checksum, business_id):
    return 'Invalid signature', 401

  # Process the webhook event
  event_type = payload.get('event')
  if event_type == 'payment.session.succeeded':
    handle_successful_payment(payload['data'])
  elif event_type == 'payment.session.failed':
    handle_failed_payment(payload['data'])

  # Return 200 to acknowledge receipt
  return 'Webhook received', 200

2. Register Your Webhook URL

Add your webhook URL to your account settings:

PATCH /accounts/settings

Request
{
  "webhook_urls": [
    "https://your-domain.com/webhooks"
  ]
}

Response
{
  "data": {
    "settings": {
      "webhook_urls": [
        "https://your-domain.com/webhooks"
      ]
    }
  }
}

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:

Store sensitive data in secure environment variables or dedicated key management systems
Implement IP whitelisting where possible
Validate all incoming webhook signatures
Use strong TLS/SSL for all connections
Rotate credentials regularly
Log and monitor access attempts
Follow the principle of least privilege

Implementation Tips:

// ❌ Avoid hardcoding secrets
const apiKey = "sk_live_123..."; // Bad practice

// ✅ Use environment variables
const apiKey = process.env.API_KEY; // Good practice

// ✅ Validate webhook signatures
const isValidSignature = verifyWebhookSignature(
  payload,
  signature,
  webhookSecret,
);

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:

{
  "checksum": "32762AE880695AE7343A649CB9C36CA6FF83AA258A139804AEF7D73B421DE097",
  "data": {
    "card_id": "81817411-9ffd-42ba-8bc8-f407b5cef9d9",
    "amount": 1000,
    "reference": "b070b0d2-e394-4783-a6f0-f10ccb3cae89",
    "currency": "USD"
  },
  "event": "card.transaction"
}

To validate:

Concatenate: event|json_encoded_data (data must be alphabetically sorted)
Create HMAC SHA-256 hash using your business ID as the key
Compare with the received checksum

The encoded data must exclude the checksum field and be in alphabetical order:

Valid Order
{"amount":1000, "card_id": "81817411-9ffd-42ba-8bc8-f407b5cef9d9", "currency": "USD", "reference": "b070b0d2-e394-4783-a6f0-f10ccb3cae89"}

2. IP Whitelisting

Whitelist these Juicyway IPs:

92.161.1
38.214.10
38.206.237
101.196.147
101.192.205
101.241.6
101.221.92

Go-Live Checklist

Verify Public Access

Ensure your webhook URL is publicly accessible (no localhost)

URL Configuration

Add trailing / if using .htaccess

Test Integration

Verify JSON parsing and 200 OK responses

Handle Long Tasks

Return 200 OK before processing lengthy operations

Monitor Failed Webhooks

Track non-200 responses in your logs

Implement Idempotency

Handle duplicate events safely

Supported Events

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

Payment Events

{
  "checksum": "",
  "event": "payment.session.created",
  "data": {
    "id": "...",
    "currency": "...",
    "amount": 1000,
    "description": "...",
    "payment_method": {},
    "status": "created",
    "customer": {
      "first_name": "...",
      "last_name": "...",
      "email": "...",
      "billing_address": {
        "line1": "...",
        "line2": "...",
        "city": "...",
        "state": "...",
        "zip_code": "...",
        "country": "..."
      }
    },
    "reference": "...",
    "metadata": {}
  }
}

{
  "checksum": "7b27d802db3b0b7c1fd3f52d1c7cfcbf11ea9a2b7987ba7c7bbe4484b36beaa8",
  "event": "payment.session.succeeded",
  "data": {
    "amount": 500,
    "currency": "CAD",
    "status": "success",
    // ... full response omitted for brevity
  }
}

{
  "checksum": "7ff8316b782cce535c0cd1f08a64b3be4a54bd05b121ddaf1d4a7e31d8f05461",
  "event": "payment.session.failed",
  "data": {
    "amount": 500,
    "status": "failed",
    "cancellation_reason": "Failed to create transaction",
    // ... full response omitted for brevity
  }
}

{
  "checksum": "",
  "event": "deposit.received",
  "data": {
    "currency": "NGN",
    "amount": 10000,
    "occured_at": "",
    "sender": "Ope Praise",
    "recipient": {
      "name": "Walter-Upton",
      "email": "alisha.schneider@hotmail.com"
    },
    "beneficiary": {
      "account_name": "Bennie Klocko",
      "account_number": "123456789"
    },
    "reference": ""
  }
}

Next Steps

Learn about API Request Authentication
Review common Error Handling
Explore the full API Reference

Home

Customers

Payments

Payment Transactions

Transfers

Exchange

Overview

Webhooks vs Polling

Setting Up Webhooks

1. Create Your Webhook URL

2. Register Your Webhook URL

Security

🔒 Security Notice

Verifying Webhook Origins

1. Checksum Validation

2. IP Whitelisting

Go-Live Checklist

Supported Events

Payment Events

Next Steps

Home

Customers

Payments

Payment Transactions

Transfers

Exchange

​Overview

​Webhooks vs Polling

​Setting Up Webhooks

​1. Create Your Webhook URL

​2. Register Your Webhook URL

​Security

🔒 Security Notice

​Verifying Webhook Origins

​1. Checksum Validation

​2. IP Whitelisting

​Go-Live Checklist

​Supported Events

​Payment Events

Next Steps

Overview

Webhooks vs Polling

Setting Up Webhooks

1. Create Your Webhook URL

2. Register Your Webhook URL

Security

Verifying Webhook Origins

1. Checksum Validation

2. IP Whitelisting

Go-Live Checklist

Supported Events

Payment Events