Webhook Setup
Enabling webhooks
To enable webhooks navigate to the integration information section of the case management. Select the required webhooks and input the following:
- Webhook URL = the URL that you'd like to receive the webhook
- Webhook Secret (optional) = a string used to sign the webhook request
If you are using standalone KYC flows within Detected (using profiles of type individuals) then we'd also recommend enabling the setting to automatically update the profile status on submission of a KYC flow. This way you can utilise the webhooks for both KYB and KYC profiles.
This setting can be found in case management on the 'Customer portal->Settings' page.
Verifying webhooks using secrets (optional)
To add an extra layer of security you can provide a secret that can be used by your downstream systems to verify the webhook.
Processing logic:
- Read the raw request body (before JSON parsing).
- Read the Signature header.
- Compute HMAC-SHA256 and compare.
Examples
Value | Source | Where it comes from |
|---|---|---|
Your webhook secret | You (dashboard) | Integration Information → Webhook Secret. Should also be stored securely in your system. |
Raw webhook request body | Detected (inbound POST) | Exact HTTP body — do not re-parse or re-serialize JSON. |
Signature header from webhook | Detected (inbound POST) | HTTP header name is "Signature" (capital S). Value is 64-char lowercase hex. |
const crypto = require('crypto');
// webhookSecret -> YOUR secret from dashboard (Webhook Secret field)
// rawBody -> RECEIVED raw HTTP body from Detected POST
// signatureHeader -> RECEIVED value of header "Signature" (capital S)
function verifyDetectedWebhook(rawBody, webhookSecret, signatureHeader) {
const expected = crypto.createHmac('sha256', webhookSecret)
.update(rawBody, 'utf8').digest('hex');
const a = Buffer.from(expected, 'utf8');
const b = Buffer.from(signatureHeader.trim(), 'utf8');
if (a.length !== b.length) return false;
return crypto.timingSafeEqual(a, b);
}
// webhookSecret = process.env.WEBHOOK_SECRET (same as dashboard)
// signatureHeader = req.headers['signature'] || req.headers['Signature']Common mistakes
Mistake | Result |
|---|---|
SHA256(body + secret) plain hash | Verification fails — use HMAC-SHA256 |
Re-serialize JSON after parsing | Verification fails — use raw body |
Base64-encode the digest | Verification fails — use lowercase hex |
Wrong secret (different webhook type) | Verification fails |
Webhook timeout and retries
Webhooks by default are fire and forget.
Whitelisting IPs
If your firewall requires whitelisting of IPs to receive the webhooks please contact us to get the required IP addresses.