Skip to main content

Webhooks

Webhooks allow your application to receive real-time updates about transaction statuses and KYC session results.

Configuration​

Configure your Webhook endpoints in the Developers > Webhooks section of the Dashboard. You will need to provide:

  • Callback URL: Where we send the POST request.
  • Events: Which events you want to subscribe to.
  • Secret: Used for HMAC signature verification.

Event Structure​

All events follow this standard envelope:

{
  "id": "evt_unique_id",
  "type": "event.type.name",
  "occurredAt": "2024-02-13T12:00:00Z",
  "companyId": "comp_123",
  "data": { ... }, // Payload specific to the event
  "version": "v1"
}

Supported Events​

kyc.session.complete​

Triggered when a user completes a KYC Flow and the final result (Approved/Rejected) is available.

{
  "type": "kyc.session.complete",
  "data": {
    "sessionId": "sess_123",
    "status": "COMPLETED",
    "customerId": "cust_456",
    "riskScore": 10,
    "riskLevel": "BAIXO" // BAIXO, MEDIO, ALTO
  }
}

transaction.updated​

Triggered when a Transaction's risk analysis is updated (e.g., from PENDING to COMPLETED risk analysis).

{
  "type": "transaction.updated",
  "data": {
    "transactionId": "TRX-789",
    "status": "COMPLETED",
    "riskScore": 85,
    "riskLevel": "ALTO"
  }
}

Security (HMAC Validation)​

Verify the X-PredictaID-Signature header to ensure the request came from us.

  1. Take the raw request body.
  2. Create an HMAC-SHA256 hash using your configured Webhook Secret.
  3. Compare the result with the header.

Node.js Example​

const crypto = require('crypto');

function verify(payload, secret, signature) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return hash === signature;
}