Developer guide
Test client onboarding guide
Step-by-step instructions for setting up webhook forwarding from your platform to OMINEX, including provider-specific wallet-address conventions and signature verification.
OMINEX uses a platform-forwarded webhook model. Your platform receives webhooks from your KYC provider, then forwards sanitized verification confirmations to OMINEX.
Why this model? KYC providers send webhooks to their customers (you), not to third parties. You control what data gets recorded. OMINEX creates an independent, timestamped record of what you report.
- OMINEX workspace created and approved.
- API key generated (Workspace → Branding & Access).
- KYC provider configured (Jumio, Trulioo, Alloy, Onfido, or Persona).
- Platform can collect wallet addresses from users during onboarding.
- Open the Branding & Access workspace.
- Generate an API key and create a webhook record for the relevant KYC provider.
- Set a webhook secret — you'll use this to sign forwarded payloads.
- Copy the generated webhook URL into your platform's outbound forwarding config.
Without a wallet address, verification is incomplete. OMINEX binds attestations to wallet addresses for on-chain enforcement and counterparty verification.
- Collect the user's wallet address during onboarding.
- Associate the wallet with the user's KYC verification record.
- Include the wallet address when forwarding to OMINEX.
Where to include wallet address by provider
{ workflowExecution: { customFields: { wallet_address: "0x..." } } }{ CustomFields: { wallet_address: "0x..." } }{ custom_data: { wallet_address: "0x..." } }{ payload: { object: { custom_data: { wallet_address: "0x..." } } } }{ data: { attributes: { fields: { wallet_address: { value: "0x..." } } } } }Reference implementation in Node.js / TypeScript:
// Your platform's webhook handler
app.post('/webhooks/kyc-provider', async (req, res) => {
const kycResult = req.body;
// 1. Verify signature from your KYC provider
if (!verifyKycProviderSignature(req)) {
return res.status(401).send('Invalid signature');
}
// 2. Look up the user's wallet address from your database
const userId = kycResult.reference_id;
const user = await db.users.findById(userId);
const walletAddress = user.wallet_address; // CRITICAL
// 3. Forward to OMINEX with wallet address
const ominexPayload = {
...kycResult,
custom_data: {
wallet_address: walletAddress,
},
};
// 4. Sign the forwarded webhook
const signature = crypto
.createHmac('sha256', OMINEX_WEBHOOK_SECRET)
.update(JSON.stringify(ominexPayload))
.digest('hex');
// 5. Forward to OMINEX
await fetch(OMINEX_WEBHOOK_URL, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Webhook-Signature': signature,
},
body: JSON.stringify(ominexPayload),
});
res.status(200).send('OK');
});Key points
- Always include the user's wallet address in the forwarded payload.
- Sign the forwarded webhook with your OMINEX webhook secret.
- Use the signature header format your provider expects.
Before forwarding production webhooks, run the helper endpoint with your test payload and secret. It computes the expected signature and (optionally) validates a signature you provide.
Request body
{
"provider": "jumio", // jumio | trulioo | alloy | onfido | persona
"payload": { ... }, // Your webhook payload (object or string)
"secret": "your_secret", // Your OMINEX webhook secret
"signature": "optional", // (Optional) Signature to verify
"timestamp": "optional" // (Optional, Persona only) Unix timestamp
}Response
{
"provider": "jumio",
"expected_signature": "ABC123...",
"header_name": "x-jumio-signature",
"signature_format": "Base64-encoded HMAC-SHA256",
"is_valid": true, // Only if signature was provided
"verification_result": "SIGNATURE_VALID",
"implementation_example": "// Node.js example..."
}- Send a sample webhook from your provider's test console.
- Verify the event appears in your OMINEX webhook events feed.
- Confirm an attestation snapshot was created for the subject.
- Verify the wallet address is correctly bound to the snapshot.