Webhooks

Set up webhooks to receive real-time notifications when verification events occur. Include a webhook_url when creating a verification request.

Webhook Events

verification.completedTenant has completed income verification
verification.failedVerification failed (e.g., bank connection error)
verification.expiredVerification link expired (7 days)

Webhook Headers

HeaderDescription
X-TenantVerify-SignatureHMAC-SHA256 signature for payload verification
X-TenantVerify-EventThe event type (e.g., verification.completed)
X-TenantVerify-TimestampISO 8601 timestamp when the webhook was sent

Example Webhook Handler

// Express.js webhook handler
app.post('/webhooks/tenantverify', (req, res) => {
  const signature = req.headers['x-tenantverify-signature'];
  const event = req.headers['x-tenantverify-event'];

  // Verify signature (recommended)
  // const isValid = verifySignature(req.body, signature);

  const { data } = req.body;

  if (event === 'verification.completed') {
    console.log('Verification completed:', data.verification_id);
    console.log('Monthly income:', data.income_report?.total_monthly_income);

    // Update your database, notify your team, etc.
  }

  res.status(200).json({ received: true });
});

Best Practices

  • Always return a 200 status code quickly to acknowledge receipt
  • Process webhooks asynchronously to avoid timeouts
  • Verify the signature to ensure the webhook is from TenantVerify
  • Handle duplicate webhooks gracefully (we may retry on failure)
← Cancel VerificationError Codes →