Webhooks

Webhooks allow you to receive real-time notifications from our platform when specific payment events occur. When configured, the platform will send an HTTP POST request to your designated endpoint.

🔧 Setup

To configure a webhook:

1. Webhook URL: Enter the endpoint URL where you want to receive webhook calls (e.g., https://example.com/webhook).

2. Event Type: Choose the event to listen for:

   • Paid: Triggered when a payment is added on the blockchain.

   • Confirmed : Triggered when a payment is confirmed on the blockchain with at least 6 blocks

3. Security Header (optional): Enable this option to include a custom signature header for verifying the authenticity of the request.

📤 Webhook Request Format

When the selected event occurs, our platform sends a POST request to your specified Webhook URL.

^{Request Headers}

The Payraze-Signature header is added to the request if you enabled the security header feature. It contains a hash of the payload sent by our platform. You need to verify it by creating a HMAC-SHA256 hash of the received payload using the provided security key.

Header	Description
Payraze-Signature (optional)	HMAC-SHA256 signature (only if Security Header is enabled)

^{Sample Payload}

{
  "event": "confirmed",
  "timestamp": "2025-07-17 20:14:32.000000",
  "payment": {
    "id": 1,
    "amount": 1.5,
    "currency": "EURC",
    "transactionHash": "0xd498ef9ba7195cf874d835d813248db389ae58a759c6569c4cd5571e07db25a2"
  }
}

^{Sample NodeJS Webhook Signature Verification}

const express = require('express');
const crypto = require('crypto');
const app = express();

// Use raw body for signature verification
app.use(express.raw({ type: 'application/json' }));

const SHARED_SECRET = 'your_shared_secret_here'; // Replace with the security header set in Payraze

app.post('/webhook', (req, res) => {
  const signature = req.headers['Payraze-Signature'];
  const rawBody = req.body;

  // Compute HMAC SHA256 digest
  const computedSignature = crypto
    .createHmac('sha256', SHARED_SECRET)
    .update(rawBody)
    .digest('hex');

  if (signature === computedSignature) {
    console.log('✅ Signature verified');
    const payload = JSON.parse(rawBody.toString());
    // Handle webhook payload here
    res.status(200).send('OK');
  } else {
    console.error('❌ Signature mismatch');
    res.status(401).send('Invalid signature');
  }
});

app.listen(3000, () => {
  console.log('Webhook listener running on port 3000');
});

🔁 Retry Logic

If your server responds with a non-200 HTTP status code, the webhook will be retried up to 5 times with exponential backoff of [30, 300, 1800] seconds, the last 2 times will each occur after 1800 seconds.

🧪 Testing

You can test your webhook integration using tools like HttpDump or by setting up a test server to inspect the incoming POST requests.

📘 Notes

• Ensure your endpoint is publicly accessible and uses HTTPS.

• The platform expects a 200 OK response within 30 seconds max.

• Timeouts or repeated failures may result in temporary suspension of webhook delivery.

For further support, contact our developer support team or refer to the developer portal.