What are Webhooks?

Webhooks are automated messages sent from payment gateways to CoinTrail when specific events occur. They allow your application to receive real-time notifications about:

• Successful payments - When a customer completes a payment
• Failed payments - When a payment attempt fails
• Subscription renewals - When a recurring subscription is charged
• Subscription cancellations - When a customer cancels their subscription
• Refunds - When a payment is refunded
• Disputes/Chargebacks - When a customer disputes a charge

Webhook Endpoint Structure

CoinTrail provides a unified webhook endpoint for all payment gateways. The URL pattern is:

https://yourdomain.com/api/webhooks/payment/{gateway}

Replace {gateway} with the gateway identifier from the table below:

Traditional Payment Gateways

Stripe

Stripe is the most popular payment gateway and requires webhook configuration for subscription management.

Setup Steps:

1. Log in to your Stripe Dashboard
2. Navigate to Developers → Webhooks
3. Click Add endpoint
4. Enter the webhook URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/stripe

5. Select the following events to listen for:
   • checkout.session.completed - When checkout is successful
   • customer.subscription.created - New subscription created
   • customer.subscription.updated - Subscription plan changed
   • customer.subscription.deleted - Subscription cancelled
   • invoice.paid - Invoice successfully paid
   • invoice.payment_failed - Payment attempt failed
   • charge.refunded - Payment refunded
   • charge.dispute.created - Chargeback initiated
6. Click Add endpoint
7. Click on the newly created webhook endpoint
8. Under Signing secret, click Reveal and copy the secret
9. Add the signing secret to your .env file:

STRIPE_WEBHOOK_SECRET=whsec_your_webhook_signing_secret_here

PayPal

PayPal webhooks are essential for handling subscription payments and IPN (Instant Payment Notification) events.

Setup Steps:

1. Log in to the PayPal Developer Dashboard
2. Select your app under My Apps & Credentials
3. Scroll down to Webhooks and click Add Webhook
4. Enter the webhook URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/paypal

5. Select the following event types:
   • PAYMENT.CAPTURE.COMPLETED - Payment captured successfully
   • PAYMENT.CAPTURE.DENIED - Payment capture denied
   • BILLING.SUBSCRIPTION.CREATED - Subscription created
   • BILLING.SUBSCRIPTION.ACTIVATED - Subscription activated
   • BILLING.SUBSCRIPTION.CANCELLED - Subscription cancelled
   • BILLING.SUBSCRIPTION.SUSPENDED - Subscription suspended
   • PAYMENT.SALE.COMPLETED - Sale completed
   • PAYMENT.SALE.REFUNDED - Sale refunded
6. Click Save
7. Copy the Webhook ID and add it to your .env:

PAYPAL_WEBHOOK_ID=your_webhook_id_here

Razorpay

Razorpay is popular in India and requires webhook configuration for payment confirmations.

Setup Steps:

1. Log in to your Razorpay Dashboard
2. Go to Settings → Webhooks
3. Click Add New Webhook
4. Enter the webhook URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/razorpay

5. Create a Secret (a strong random string)
6. Select events:
   • payment.captured
   • payment.failed
   • subscription.charged
   • subscription.cancelled
   • subscription.halted
   • refund.created
7. Click Create Webhook
8. Add the secret to your .env:

RAZORPAY_WEBHOOK_SECRET=your_webhook_secret_here

Paystack

Paystack is popular in Africa (Nigeria, Ghana, South Africa, Kenya).

Setup Steps:

1. Log in to your Paystack Dashboard
2. Go to Settings → API Keys & Webhooks
3. Under Webhook URL, enter:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/paystack

4. Click Save

Paystack automatically sends the following events:

• charge.success - Successful payment
• subscription.create - New subscription
• subscription.disable - Subscription cancelled
• invoice.payment_failed - Payment failed
• refund.processed - Refund completed

Paystack webhooks are verified using your secret key. The signature is sent in the X-Paystack-Signature header.

Flutterwave

Flutterwave supports payments across Africa with multiple currencies.

Setup Steps:

1. Log in to your Flutterwave Dashboard
2. Go to Settings → Webhooks
3. Enter the webhook URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/flutterwave

4. Set your Secret Hash (this verifies webhooks)
5. Add the secret hash to your .env:

FLUTTERWAVE_SECRET_HASH=your_secret_hash_here

Flutterwave sends the secret hash in the verif-hash header for verification.

Mollie

Mollie is popular in Europe (Netherlands, Belgium, Germany, etc.).

Setup Steps:

1. Log in to your Mollie Dashboard
2. Go to Developers → Webhooks
3. Enter the webhook URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/mollie

Mollie doesn't use signature verification. Instead, when you receive a webhook, CoinTrail calls the Mollie API to verify the payment status automatically.

Cryptocurrency Payment Gateways

CoinGate

CoinGate allows you to accept Bitcoin, Ethereum, and 50+ other cryptocurrencies.

Setup Steps:

1. Log in to your CoinGate Dashboard
2. Go to Account → API → Callback URL
3. Set the callback URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/coingate

CoinGate verifies callbacks using:

• IP Whitelisting - Only accepts callbacks from CoinGate's IP addresses
• Token verification - A unique token is included in each callback

NOWPayments

NOWPayments supports 150+ cryptocurrencies with instant exchange.

Setup Steps:

1. Log in to your NOWPayments Dashboard
2. Go to Store Settings → IPN
3. Enable IPN Callback
4. Set the IPN Callback URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/nowpayments

5. Copy your IPN Secret Key
6. Add it to your .env:

NOWPAYMENTS_IPN_SECRET=your_ipn_secret_key_here

NOWPayments uses HMAC-SHA512 signatures with sorted payload for verification. The signature is sent in the x-nowpayments-sig header.

Coinbase Commerce

Coinbase Commerce allows you to accept Bitcoin, Ethereum, Litecoin, and other popular cryptocurrencies.

Setup Steps:

1. Log in to Coinbase Commerce
2. Go to Settings → Webhooks
3. Click Add an endpoint
4. Enter the webhook URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/coinbase_commerce

5. Copy the Shared Secret shown
6. Add it to your .env:

COINBASE_COMMERCE_WEBHOOK_SECRET=your_shared_secret_here

Coinbase Commerce uses HMAC-SHA256 signatures. The signature is sent in the X-CC-Webhook-Signature header.

Cryptomus

Cryptomus offers crypto payment processing with low fees.

Setup Steps:

1. Log in to your Cryptomus Dashboard
2. Go to Settings → Webhooks
3. Set the callback URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/cryptomus

Cryptomus includes a sign parameter in the payload calculated as base64(MD5(json + api_key)).

Binance Pay

Binance Pay allows users to pay with crypto from their Binance wallet.

Setup Steps:

1. Log in to Binance Merchant Portal
2. Go to Account → Webhooks
3. Add your webhook URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/binance_pay

Binance Pay sends three headers for verification:

• BinancePay-Timestamp
• BinancePay-Nonce
• BinancePay-Signature (HMAC-SHA512)

Regional Payment Gateways

Paytm (India)

1. Log in to Paytm Dashboard
2. Go to Developer Settings → Callback URL
3. Set the callback URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/paytm

Paytm uses checksum verification with the CHECKSUMHASH parameter.

Instamojo (India)

1. Log in to Instamojo Dashboard
2. Go to Developers → Webhooks
3. Add your webhook URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/instamojo

Instamojo uses HMAC-SHA1 signatures with the mac parameter.

Monnify (Nigeria)

1. Log in to Monnify Dashboard
2. Go to Settings → Notifications
3. Set the webhook URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/monnify

Monnify includes a transactionHash (SHA512) for verification.

Skrill (Europe)

1. Log in to your Skrill Merchant Account
2. Go to Developer Settings → Status URL
3. Set the status URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/skrill

Skrill uses MD5 signatures with the md5sig parameter.

2Checkout

1. Log in to 2Checkout Dashboard
2. Go to Integrations → Webhooks & API
3. Under INS (Instant Notification Service), set the URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/2checkout

Authorize.net

1. Log in to Authorize.net Merchant Interface
2. Go to Account → Transaction Format Settings → Webhooks
3. Click Add Webhook
4. Set the webhook URL:
   URLCopy

   https://yourdomain.com/api/webhooks/payment/authorize_net

Authorize.net uses HMAC-SHA512 signatures in the X-ANET-Signature header.

Testing Webhooks

Before going live, test your webhook configuration to ensure everything works correctly.

Stripe CLI (Recommended for Stripe)

The Stripe CLI allows you to forward webhooks to your local development environment:

# Install Stripe CLI
# macOS: brew install stripe/stripe-cli/stripe
# Windows: scoop install stripe

# Login to your Stripe account
stripe login

# Forward webhooks to your local server
stripe listen --forward-to http://localhost/api/webhooks/payment/stripe

# Trigger a test event
stripe trigger checkout.session.completed

ngrok (For All Gateways)

Use ngrok to expose your local server to receive webhooks during development:

# Install ngrok from https://ngrok.com/

# Expose your local server
ngrok http 80

# Use the generated URL (e.g., https://abc123.ngrok.io) in your gateway settings

Webhook.site (Quick Testing)

Use webhook.site to inspect webhook payloads before connecting to CoinTrail. This helps you understand the data structure each gateway sends.

Webhook Security

CoinTrail implements multiple security measures for webhooks:

Security Best Practices

• Signature Verification - All webhooks with signature support are verified before processing
• HTTPS Required - Always use HTTPS for webhook endpoints in production
• IP Whitelisting - Some gateways (like CoinGate) only send webhooks from specific IPs
• Idempotency - CoinTrail handles duplicate webhook events gracefully
• Logging - All webhook events are logged for debugging and audit purposes

Signature Headers by Gateway

Troubleshooting

Common Issues

Viewing Webhook Logs

Check webhook activity in multiple places:

1. Laravel Logs - storage/logs/laravel.log contains detailed webhook processing logs
2. Gateway Dashboard - Most gateways show webhook delivery history with request/response details