Webhooks

Webhook setup guide for TransX402 — receive real-time payment notifications, verify SHA-256 signatures, and understand the retry policy.

Overview

Webhooks allow your server to receive real-time notifications when payments occur. Instead of polling the API to check payment status, TransX402 will send an HTTP POST request to a URL you specify whenever a payment event happens.

Setting Up Webhooks

1. Configure Your Webhook URL

Go to the Settings page in the TransX402 dashboard and enter your webhook URL:

https://myblog.com/webhook/transx402

Or via API:

curl -X PATCH https://api.transx402.com/merchant/me \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://myblog.com/webhook/transx402",
    "webhookSecret": "auto"
  }'

When webhookSecret is set to "auto", the system will auto-generate a secret. This secret is used to sign the webhook payload.

2. Implement Your Webhook Endpoint

Create an endpoint on your server that receives POST requests from TransX402:

// Express.js
app.post('/webhook/transx402', (req, res) => {
  const payload = req.body;
 
  // Verify signature (important!)
  if (!verifySignature(req, payload)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
 
  // Process the event
  switch (payload.event) {
    case 'payment.confirmed':
      handlePaymentConfirmed(payload.data);
      break;
    case 'payment.failed':
      handlePaymentFailed(payload.data);
      break;
  }
 
  // Always respond with 200 to acknowledge receipt
  res.status(200).json({ received: true });
});

Webhook Payload

Format

{
  "event": "payment.confirmed",
  "data": {
    "txHash": "0x...",
    "paymentId": "pay_...",
    "status": "confirmed",
    "from": "0xPayer",
    "to": "0xMerchant",
    "token": "IDRX",
    "amount": "500000",
    "network": "base",
    "resource": "https://example.com/article/123",
    "timestamp": "2026-04-01T10:30:00Z"
  }
}

The signature is in the X-TransX402-Signature header (sha256=<hex>), not inside the JSON body. Also sent: X-TransX402-Event, X-TransX402-Delivery.

Event Types

Signature Verification

Every webhook request includes an X-TransX402-Signature header. The value is sha256= plus SHA-256 of webhookSecret + rawBody (string concatenation — not crypto.createHmac). Verify against the raw request bytes.

Node.js

import crypto from 'crypto';
 
function verifyWebhookSignature(rawBody, signature, webhookSecret) {
  const expectedSignature = 'sha256=' + crypto
    .createHash('sha256')
    .update(webhookSecret + rawBody)
    .digest('hex');
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Python

import hmac
import hashlib
 
def verify_webhook_signature(body: bytes, signature: str, webhook_secret: str) -> bool:
    expected = 'sha256=' + hashlib.sha256(
        webhook_secret.encode() + body
    ).hexdigest()
 
    return hmac.compare_digest(signature, expected)

PHP

function verifyWebhookSignature($body, $signature, $webhookSecret) {
    $expected = 'sha256=' . hash('sha256', $webhookSecret . $body);
    return hash_equals($expected, $signature);
}

Retry Policy

If your webhook endpoint does not respond with a 2xx status code (200-299), TransX402 will retry delivery with exponential backoff:

After 5 failed attempts, the webhook is considered failed and will not be retried. You can view webhook delivery status on the Settings page in the dashboard.

Tips for Webhook Endpoints

1. Respond quickly — Return 200 as soon as possible, process the event asynchronously if needed
2. Be idempotent — Ensure your endpoint can receive the same event more than once without side effects (webhooks may be resent)
3. Verify signatures — Always verify X-TransX402-Signature against the raw body
4. Log all events — Keep a log of received webhooks for debugging

Testing Webhooks

Send a Test Event

You can send a test event from the Settings page in the dashboard by clicking the "Send Test Event" button. This will send a test webhook payload to your webhook URL.

Use the Sandbox

All sandbox payments also trigger webhooks. This lets you test the entire webhook flow without making real payments:

1. Set your webhook URL in the dashboard
2. Make a sandbox payment
3. Check that the webhook was received correctly
4. Verify that signature validation works
5. Ensure your business logic processes the event correctly

Debugging Tools

For testing and debugging, you can use tools like:

• webhook.site — Receive and inspect webhook requests in real-time
• ngrok — Expose localhost to the internet to receive webhooks during development

# Example using ngrok
ngrok http 3000
# Use the ngrok URL as your webhook URL in the dashboard
# https://abc123.ngrok.io/webhook/transx402

Delivery Status

On the Settings page in the dashboard, you can view webhook delivery statistics:

• Total — Total number of webhooks sent
• Delivered — Number of webhooks successfully received (2xx response)
• Failed — Number of webhooks that failed after all retries

Each webhook delivery is recorded in the database for audit trail and debugging purposes.