Affitti e gestione immobiliare
Invii il link ospitato nella stessa email della domanda di locazione. Il webhook imposta il candidato come verificato nel Suo sistema prima che Lei esamini il fascicolo.
Webhook e integrazioni
Webhook per la verifica dell'identità, una pagina ospitata e un widget.
Indirizzi un candidato a una pagina di verifica ospitata o inserisca il widget nel Suo flusso, riceva un webhook firmato nel momento in cui il risultato è disponibile e permetta a chiunque abbia il link di confermarlo su una pagina pubblica di verifica delle credenziali. Un'integrazione API KYC pensata per andare in produzione in un pomeriggio.
- Callback firmati con HMAC-SHA256
- Passaggio con QR dal desktop al telefono
- Le sessioni sandbox non vengono mai fatturate
Pagina di verifica ospitata
Un solo link per l'intero flusso.
Crei una sessione tramite l'API e riceverà un URL di verifica. Lo invii via email, SMS o nella Sua app: alla pagina pensa al resto.
Desktop
Il richiedente apre il link dalla propria scrivania.
Passaggio tramite QR
La pagina mostra un codice QR e una breve scheda con le istruzioni.
Acquisizione da telefono
La scansione porta la stessa sessione all'acquisizione del documento e del selfie.
Verificato
La sessione raggiunge lo stato VERIFIED, sempre sul telefono.
Di nuovo da Lei
Un reindirizzamento al Suo URL di ritorno, più un webhook firmato, in entrambi i casi.
Funziona come un reindirizzamento di pagamento
Il richiedente arriva su una pagina all'URL dedicato della Sua sessione. Nessun account, nessuna app da installare.
Passaggio da desktop a telefono tramite QR
Aperta su desktop, la pagina mostra un codice QR e una breve scheda di istruzioni invece di richiedere l'accesso alla fotocamera. La scansione apre lo stesso link sul telefono, che passa direttamente all'acquisizione del documento e del selfie.
Torna da Lei, con la risposta
Quando la sessione raggiunge VERIFIED, la pagina reindirizza al Suo URL di ritorno con l'ID di sessione e lo stato aggiunti, così la Sua app sa cos'è successo senza attendere nient'altro.
Con il Suo marchio, nei piani idonei
Il nome della Sua azienda, il logo, il colore di accento e i link ai termini e alla privacy, applicati alla pagina ospitata e alla pagina di verifica delle credenziali.
Webhook
Una callback firmata, nel momento in cui il risultato è pronto.
Ci indichi un URL di webhook quando crea una sessione e vi invieremo il risultato non appena la sessione termina, senza bisogno di polling.
Firmato, non solo inviato
Ogni invio include un header X-Bio-Signature: un HMAC-SHA256 del corpo della richiesta, così potrà verificare che provenga da noi prima di fidarsi.
Ritentato, non «invia e dimentica»
Un invio non riuscito viene ritentato tre volte, con un'attesa più lunga prima di ogni tentativo.
Ogni tentativo viene registrato
Riuscito o fallito, conserviamo una registrazione del tentativo da parte nostra.
Prossimamente Un registro degli invii all'interno del portale, per consentirLe di vedere di persona ogni tentativo, sarà disponibile prossimamente.
Consideri l'ultimo VERIFIED come la verità
A causa dei nuovi tentativi, in rari casi un invio può arrivare fuori ordine. Non basi la Sua logica sulla ricezione di un webhook: la basi sull'ID di sessione e lasci che un VERIFIED successivo sovrascriva uno precedente. Se mantiene un proprio stato, elimini i duplicati in base all'ID di sessione anziché alla ricezione del webhook.
Verificare la firma
Verifichi l'attendibilità del payload prima di agire.
Ricalcoli l'HMAC-SHA256 sul corpo grezzo della richiesta e lo confronti con X-Bio-Signature prima di elaborare qualsiasi dato.
javascript
const crypto = require("crypto");
function verifySignature(rawBody, signatureHeader, secret) {
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(signatureHeader || "", "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// Read the raw body — don't let a JSON body-parser touch it first.
app.post("/hooks/shieldid", express.raw({ type: "application/json" }), (req, res) => {
const signature = req.header("X-Bio-Signature") || "";
if (!verifySignature(req.body, signature, process.env.SHIELDID_WEBHOOK_SECRET)) {
return res.status(401).send("invalid signature");
}
const event = JSON.parse(req.body);
// Treat the latest VERIFIED status as authoritative; de-duplicate by session_id.
res.status(200).send("ok");
});Widget JS
Il flusso ospitato, inserito nella Sua pagina.
Il widget crea una sessione e mostra lo stesso flusso ospitato in linea, in un iframe, così i richiedenti non lasciano mai il Suo sito.
- Viene visualizzato in un iframe con accesso a fotocamera e microfono, dimensionato sul proprio contenitore.
- Legge lo stato della sessione allo stesso modo della pagina ospitata: tramite il Suo URL di ritorno e il Suo webhook, una volta terminata la sessione.
Prossimamente I callback di completamento in pagina (onComplete, onCancel, onStep, ridimensionamento automatico) saranno disponibili a breve. Fino ad allora, utilizzi return_url e i webhook per sapere quando una sessione termina — funzionano già oggi.
Prima di passare in produzione
Attualmente il widget accetta una chiave API direttamente nel browser. Lo consideri una comodità per la sandbox, non un modello da produzione: crei la sessione dal Suo backend mantenendo la chiave lato server e fornisca al widget solo la sessione risultante, mai una chiave live che il browser di un visitatore possa leggere.
html
<script src="https://cdn.shieldid.ca/sdk/v1/widget.js"></script>
<div id="shieldid-verify"></div>
<script>
TLVerify.init({
apiKey: "vk_sand_your_key", // sandbox only — see the note above for production
containerId: "shieldid-verify",
returnUrl: "https://yourapp.example/verified",
webhookUrl: "https://yourapp.example/hooks/shieldid",
locale: "en",
});
</script>Pagina di verifica delle credenziali
Una pagina pubblica per una sessione verificata.
Una volta che una sessione raggiunge VERIFIED, il suo link di verifica delle credenziali mostra una conferma in linguaggio semplice: il nome del candidato, il tipo di documento e lo stato. Chiunque abbia il link — un cofirmatario, un addetto alla reception, una controparte — può confermare il risultato senza accedere alla Sua dashboard.
Jordan Reyes
Dati di esempioPatente di guida della California
Verificato
- Non è richiesto alcun accesso per visualizzarla.
- Non vi compare mai alcuna immagine grezza del documento né alcun punteggio di affidabilità — uno stato e l'identità, nient'altro.
- Con lo stesso branding della pagina ospitata, sui piani idonei.
Modelli di integrazione
Come sei tipi di aziende configurano il tutto.
Gli elementi di base sono gli stessi ovunque: una sessione, un link o un widget, un webhook. Il modello adatto cambia in base a come e quando Le serve la risposta.
Settore legale e studi legali
Invii il link durante l'accoglienza del cliente e conservi la ricevuta del webhook nel fascicolo, così che l'identificazione del cliente risulti agli atti prima dell'inizio dell'incarico.
Associazioni di condominio e HOA
Rimandi dal modulo di registrazione di proprietari o inquilini che il consiglio già utilizza; il risultato arriva prima che l'unità venga aggiunta al registro.
Fintech e prestiti
Il webhook attiva automaticamente il Suo passaggio di valutazione del rischio, così un candidato non attende mai che una persona si accorga dell'arrivo di un risultato.
Marketplace e piattaforme gig
Incorpori il widget nell'onboarding di venditori o autisti per un flusso che non esce mai dalla Sua app; crei la sessione dal Suo backend, come raccomandato sopra.
E-signature
Avvii il flusso ospitato prima dell'inizio della cerimonia di firma e subordini il rilascio dei documenti al webhook, non alla semplice parola del richiedente.
Domande
Risposte dirette sull'integrazione.
Inizia ora
Configuri un webhook. Lo veda in azione.
Crei una sessione sandbox con un URL di webhook, esegua una verifica sul Suo telefono e legga la callback firmata che viene inviata.