Skip to main content

​
Overview

Webhooks allow TXCloud to push real-time notifications to your server when events occur. Instead of polling our API, you receive updates automatically.

​
How Webhooks Work

​
Setting Up Webhooks

​
Step 1: Create a Webhook Endpoint

Create an endpoint on your server to receive webhook events: 
// Express.js example
app.post('/webhooks/txcloud', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-txcloud-signature'];
  const payload = req.body;
  
  // Verify signature
  if (!verifySignature(payload, signature, webhookSecret)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  
  // Handle the event
  switch (event.type) {
    case 'identity.verification.completed':
      handleVerificationCompleted(event.data);
      break;
    case 'fraud.signal.detected':
      handleFraudSignal(event.data);
      break;
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }
  
  res.status(200).send('OK');
});

​
Step 2: Register Your Webhook

const webhook = await txcloud.developers.webhooks.create({
  url: 'https://yourapp.com/webhooks/txcloud',
  events: [
    'identity.verification.completed',
    'identity.verification.failed',
    'transaction.scored',
    'fraud.signal.detected'
  ],
  description: 'Production webhook'
});

// Save the secret for signature verification
console.log('Webhook Secret:', webhook.secret);

​
Webhook Events

​
Identity Events

EventDescription
identity.verification.completedVerification finished successfully
identity.verification.failedVerification failed
identity.session.expiredSession expired before completion

​
Fraud Events

EventDescription
fraud.signal.detectedFraud signal detected
fraud.device.blockedDevice added to blocklist
fraud.rule.triggeredCustom rule was triggered

​
Transaction Events

EventDescription
transaction.scoredTransaction was scored
transaction.review_requiredManual review needed
transaction.fraud_detectedFraud confirmed

​
Lending Events

EventDescription
lending.assessment.completedCredit assessment finished
lending.statement.analyzedBank statement analysis complete
lending.monitor.alertMonitoring alert triggered

​
Watchlist Events

EventDescription
watchlist.screening.completedScreening finished
watchlist.match.foundPotential match found
watchlist.monitor.alertOngoing monitoring alert

​
Event Payload

All webhook events follow this structure: 
{
  "id": "evt_a1b2c3d4e5f6",
  "type": "identity.verification.completed",
  "created_at": "2025-01-15T10:30:00Z",
  "api_version": "2025-01-01",
  "data": {
    "id": "ver_xyz789",
    "status": "verified",
    "extracted_data": { ... },
    "checks": { ... }
  }
}
FieldTypeDescription
idstringUnique event ID
typestringEvent type
created_atdatetimeWhen event was created
api_versionstringAPI version used
dataobjectEvent-specific payload

​
Signature Verification

Always verify webhook signatures to ensure events are from TXCloud.
TXCloud signs all webhook payloads using HMAC-SHA256: 
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  const signatureBuffer = Buffer.from(signature, 'hex');
  const expectedBuffer = Buffer.from(expectedSignature, 'hex');
  
  return crypto.timingSafeEqual(signatureBuffer, expectedBuffer);
}
The signature is sent in the X-TXCloud-Signature header: 
POST /webhooks/txcloud HTTP/1.1
Host: yourapp.com
Content-Type: application/json
X-TXCloud-Signature: a1b2c3d4e5f6...
X-TXCloud-Timestamp: 1705312800

{"id": "evt_abc123", ...}

​
Retry Policy

If your endpoint fails to respond with a 2xx status, TXCloud will retry:
AttemptDelay
1Immediate
21 minute
35 minutes
430 minutes
52 hours
612 hours
724 hours
After 7 failed attempts, the webhook is marked as failed and we’ll notify you via email.
Return a 2xx response as quickly as possible. Process events asynchronously to avoid timeouts.

​
Best Practices

Return a 200 response immediately, then process asynchronously:
app.post('/webhooks', (req, res) => {
  // Respond immediately
  res.status(200).send('OK');
  
  // Process asynchronously
  processEvent(req.body).catch(console.error);
});
Events may be delivered more than once. Use the event id for idempotency:
if (await eventAlreadyProcessed(event.id)) {
  return; // Skip duplicate
}
For high-volume webhooks, push events to a queue:
  • Amazon SQS
  • Redis Queue
  • RabbitMQ
Check webhook delivery status in your dashboard. Failed webhooks are logged with error details.

​
Testing Webhooks

​
Send a Test Event

// Send a test event to your endpoint
await txcloud.developers.webhooks.test(webhookId, {
  event_type: 'identity.verification.completed'
});

​
Local Development

Use a tunneling service for local testing: 
# Using ngrok
ngrok http 3000

# Your local endpoint becomes accessible at:
# https://abc123.ngrok.io/webhooks/txcloud

​
Webhook Logs

View delivery logs in the dashboard or via API: 
const logs = await txcloud.developers.webhooks.deliveries(webhookId, {
  limit: 20,
  status: 'failed'  // or 'success'
});

logs.data.forEach(log => {
  console.log(`${log.event_type}: ${log.response_status} - ${log.created_at}`);
});

Webhook Dashboard

View and manage webhooks in your dashboard