Webhooks

Receive real-time notifications when payments are processed

Overview

Webhooks allow you to receive HTTP POST notifications when events occur in your x402Tele account. This is useful for tracking payments, updating user balances, or triggering automated workflows.

Webhook Events

payment.succeeded

A payment was successfully processed

payment.failed

A payment attempt failed

Setting Up Webhooks

1
Go to Dashboard → Webhooks
2
Enter your webhook endpoint URL
3
Copy your webhook signing secret
4
Enable webhooks and save

Webhook Payload

All webhook events include the following structure:

{
  "id": "evt_abc123",
  "type": "payment.succeeded",
  "created": 1699999999,
  "data": {
    "receipt": {
      "tx_ref": "5KJp8...",
      "amount": 0.05,
      "currency": "USDC",
      "chain": "solana",
      "command": "analyze",
      "user_id": "tg:123",
      "idempotency_key": "abc-123",
      "ts": "2025-11-05T10:00:00Z",
      "settlement_ms": 1850,
      "signature": "7f8a9b..."
    }
  }
}

Verifying Signatures

Always verify webhook signatures to ensure the request came from x402Tele:

import crypto from 'crypto';

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

// In your webhook endpoint
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process event
  const event = req.body;
  
  if (event.type === 'payment.succeeded') {
    // Handle successful payment
    console.log('Payment received:', event.data.receipt);
  }
  
  res.status(200).send('OK');
});

Best Practices

Always verify webhook signatures
Respond with 200 within 5 seconds
Process webhooks asynchronously
Handle duplicate deliveries (use event ID)
Log all webhook events for debugging

Retry Logic

If your endpoint returns a non-200 status or times out, x402Tele will retry with exponential backoff:

1
Attempt 1: Immediate
2
Attempt 2: 1 minute later
3
Attempt 3: 5 minutes later
4
Attempt 4: 30 minutes later
5
Attempt 5: 2 hours later
Retry Strategy
Webhooks are retried up to 5 times with exponential backoff. After all attempts fail, the event is marked as failed in your dashboard.