Webhooks

Webhooks allow your application to receive asynchronous updates about KYC lifecycle, customer resolution, flow publishing, and KYT pipeline events.

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

Common emitted event types are:

• session.created
• session.completed
• customer.identified
• flow.version.published
• kyt.transaction.queued
• kyt.transaction.reprocess.requested
• kyt.transaction.pipeline.completed
• kyt.transaction.dead_lettered

For full payload samples and field descriptions, see Webhook Events Reference.

Security (HMAC Validation)

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

1. Preserve the raw JSON body exactly as received.
2. Create an HMAC-SHA256 hash using your configured Webhook Secret.
3. Compare the result with the header.

Additional headers sent with each webhook request:

• X-PredictAid-Event-ID: unique event identifier.
• X-PredictAid-Signature: HMAC-SHA256 signature.
• User-Agent: PredictAid-Webhook-Dispatcher/1.0.

Webhook handlers should return a 2xx response after durable receipt. Process duplicate events idempotently by event ID because network retries can happen.

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;
}

In production frameworks, prefer validating against the raw request body captured before JSON parsing whenever possible.

Delivery Behavior

PredictaID sends each event as an HTTP POST with Content-Type: application/json. Your endpoint should respond quickly and queue longer processing internally.

Recommended handler behavior:

• Reject events with invalid signatures.
• Store X-PredictAid-Event-ID before processing.
• Treat duplicate event IDs as already received.
• Return 2xx only when the event is durably stored or safely queued.
• Log request ID, event ID, aggregate ID, and event type without logging sensitive personal data.