Webhooks guide

Webhooks are the backbone of a reliable CashXChain integration.

Handler design

Your handler should:

1. Read the raw request body.
2. Verify signature.
3. Check timestamp tolerance.
4. Store event ID.
5. Deduplicate if already processed.
6. Acknowledge with 2xx quickly.
7. Process event asynchronously.
8. Fetch the latest resource state if needed.

Pseudocode

app.post('/cashxchain/webhooks', async (req, res) => {
  const rawBody = req.rawBody;
  const signature = req.header('X-CXC-Signature');
  const timestamp = req.header('X-CXC-Timestamp');

  verifyCashXChainSignature(rawBody, signature, timestamp, webhookSecret);

  const event = JSON.parse(rawBody.toString('utf8'));
  if (await alreadyProcessed(event.id)) {
    return res.sendStatus(200);
  }

  await storeEvent(event);
  await enqueueEventProcessing(event.id);
  return res.sendStatus(200);
});

Ordering

Events may arrive out of order. Fetch the current payment or account state before making irreversible decisions.

Retries

CashXChain retries failed deliveries. Make your handler idempotent.

Monitoring

Monitor:

• 2xx response rate.
• Signature verification failures.
• Queue latency.
• Duplicate events.
• Unhandled event types.
• Delivery failure alerts.