Skip to main content

​
What are Webhooks?

Webhooks are HTTP callbacks that HopNow sends to your application when specific events occur. Instead of repeatedly polling our API for changes, webhooks provide real-time notifications about important events like completed payments, account updates, and more.

​
How Webhooks Work

1

Configure Webhook Endpoint

Create a webhook endpoint in your application and register it with HopNow
2

Event Occurs

An event happens in your HopNow account (e.g., payment completes)
3

Webhook Sent

We send an HTTP POST request to your endpoint with event details
4

Process Event

Your application receives and processes the webhook data
5

Respond

Your endpoint returns a 2xx status code to acknowledge receipt

​
Webhook Events

​
Payment Events

  • payin.created - Incoming payment initiated
  • payin.completed - Incoming payment successful
  • payin.failed - Incoming payment failed
  • payout.created - Outgoing payment initiated
  • payout.completed - Outgoing payment successful
  • payout.failed - Outgoing payment failed

​
Account Events

  • account.created - New account created
  • account.updated - Account information changed
  • account.deactivated - Account deactivated

​
FX Events

  • fx_quote.created - Foreign exchange quote generated
  • fx_quote.expired - FX quote expired

​
Infrastructure Events

  • virtual_account.created - Virtual account created
  • wallet.created - Crypto wallet created

​
Security

​
Signature Verification

All webhooks are signed with HMAC-SHA256 using your webhook secret: 
import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

​
HTTPS Required

All webhook URLs must use HTTPS to ensure data security in transit.

​
Delivery and Retries

​
Retry Strategy

  • Immediate failure: Retry after 1 minute
  • Continued failure: Exponential backoff (5m, 15m, 1h, 6h)
  • Maximum attempts: 5 retries over 24 hours

​
Success Criteria

Your endpoint must:
  • Respond with 2xx status code
  • Respond within 30 seconds
  • Return response quickly (process asynchronously if needed)

​
Best Practices

​
1. Idempotency

Handle duplicate events gracefully: 
def process_webhook(event):
    if already_processed(event['id']):
        return "OK"  # Already handled
    
    # Process event...
    mark_as_processed(event['id'])

​
2. Async Processing

Return success quickly, process in background: 
@app.route('/webhook', methods=['POST'])
def webhook_handler():
    event = request.json
    
    # Quick validation
    if not verify_signature(request):
        return "", 401
    
    # Queue for background processing
    process_webhook_async.delay(event)
    
    return "", 200  # Return immediately

​
3. Error Handling

Log errors but don’t block webhooks: 
def safe_process_webhook(event):
    try:
        process_event(event)
    except Exception as e:
        logger.error(f"Webhook processing failed: {e}")
        # Don't re-raise - prevents infinite retries

​
Getting Started

  1. Create a webhook endpoint in your application
  2. Register it with HopNow
  3. Implement signature verification
  4. Test with sample events
Ready to implement webhooks? Start with our security guide or jump to creating your first endpoint.