Skip to main content

Webhooks

GOPayments uses webhooks to provide real-time information about all GOPayments activity. This enables you to deliver products to your users after receiving successful payments, enable subscriptions after successful payments, and receive instant notifications about payment status changes.

GOPayments sends messages as a JSON payload via POST request to all active registered webhooks. Webhooks currently receive data about all notifications including instant payments, scheduled payouts, and system events.

For each message that is not successfully sent, GoPayments will attempt retries every up to a maximum of 9 times. You can also view the webhook messages in the Developer Webhook page in the GoPayments Dashboard by clicking on a webhook and trigger retries if needed.

What are Webhooks?​

Webhooks are HTTP callbacks that GOPayments sends to your application when specific events occur. They provide real-time notifications about:

  • Payment status changes
  • Payout completions and failures
  • Customer account updates
  • Subscription events
  • System notifications
  • Instant payment confirmations

Setting Up Webhooks​

Step 1: Access Webhook Settings​

  1. Log in to your GOPayments dashboard
  2. Navigate to "Settings" → "Developers" → "Webhooks"
  3. Click "Create New Webhook"

Step 2: Configure Webhook​

  1. Webhook URL

    • Enter your endpoint URL (must be HTTPS)
    • Example: https://your-domain.com/webhooks/gopayments

  2. Event Selection

    • Choose which events to receive notifications for
    • Select "All Events" or specific event types

  3. Security Settings

    • Enable webhook signature verification
    • Configure authentication if needed

  4. Test Webhook

    • Send a test webhook to verify configuration
    • Check your endpoint receives the test message

Instant Payments Notifications​

GOPayments sends instant notifications for all payment-related events to keep your application synchronized with real-time payment status changes.

Payment Events​

payment.completed​

Triggered when a payment is successfully completed:

{
    "type": "checkoutSession.success",
    "data":
    {
        "paymentIntentId": "pi_test_TJ74Z_JsCbQ9",
        "paymentStatus": "SUCCESS",
        "merchantReference": "25052180019",
        "payToken": "SOL",
        "payNetwork": "SOLANA",
        "payAmount": 0.02,
        "tokenRate": 115.5,
        "paymentIntentTitle": "Order F4670813NB",
        "paymentIntentDescription": "",
        "currencyCode": "USD",
        "paymentIntentAmount": 2.31,
        "at": 1747793578527,
        "transactionHistory":
        [
            {
                "fromAddress": "A8JdL7KEdjAfJSYxu2HnaDMRjSNpZaBfuohFqZme8CCs",
                "toAddress": "8GU8jDEQtqh3pwRUx4zr4qxBz6hQimYZDaRNS7rVKJJR",
                "amount": 0.02,
                "signature": "4LePQVGaMaZfRbJcKfuF57nrYxjAE2DPAdLDmSgGbTdpVoDDxUiho5x1qMFBqgkS5JLmJ3wSAZSWsXEuSvXhmuDg"
            }
        ],
        "actuallyPaidAmount": 0.02,
        "actuallyPaidEstimateFiatAmount": 3.3486
    }
}

Webhook Security​

Signature Verification​

GOPayments signs webhook payloads to ensure authenticity:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

// Usage
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-gopayments-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(400).send('Invalid signature');
  }
  
  // Process webhook
  res.status(200).send('OK');
});

Getting Started​

Ready to set up webhooks? Follow these steps:

  1. Create Webhook Endpoint: Set up HTTPS endpoint
  2. Configure Webhook: Add webhook URL in dashboard
  3. Test Webhook: Send test webhook to verify
  4. Handle Events: Implement event handling logic
  5. Monitor: Watch webhook delivery logs
  6. Optimize: Improve performance and reliability

GOPayments webhooks keep your application synchronized with real-time payment events. Start receiving instant notifications today!