Locação e administração de imóveis
Envie o link hospedado no mesmo e-mail da solicitação de aluguel. O webhook marca o candidato como verificado no seu sistema antes de você analisar o dossiê.
Webhooks e integrações
Webhooks de verificação de identidade, uma página hospedada e um widget.
Envie o candidato a uma página de verificação hospedada ou coloque o widget no seu próprio fluxo, receba um webhook assinado assim que o resultado estiver pronto e deixe qualquer pessoa com o link confirmá-lo em uma página pública de verificação de credencial. Uma integração de API de KYC feita para entrar no ar em uma tarde.
- Callbacks assinados com HMAC-SHA256
- Transferência por QR code do computador para o celular
- Sessões de sandbox nunca são cobradas
Página de verificação hospedada
Um link faz o fluxo inteiro.
Crie uma sessão pela API e você recebe uma URL de verificação. Envie por e-mail, SMS ou no seu próprio app — a página cuida do resto.
Computador
O solicitante abre o link na mesa de trabalho.
Transferência por QR
A página mostra um QR code e um breve cartão de instruções.
Captura no celular
Ao escanear, a mesma sessão passa para a captura do documento e da selfie.
Verificado
A sessão chega a VERIFIED, ainda no celular.
De volta para você
Um redirecionamento para a sua URL de retorno, além de um webhook assinado, em qualquer caso.
Funciona como um redirecionamento de pagamento
O solicitante chega a uma página na URL da própria sessão. Sem conta, sem app para instalar.
Transferência por QR, do computador para o celular
Aberta em um computador, a página mostra um QR code e um breve cartão de instruções em vez de pedir acesso à câmera. Ao escaneá-lo, o mesmo link abre no celular, que passa direto para a captura do documento e da selfie.
Volta para você, com a resposta
Quando a sessão chega a VERIFIED, a página redireciona para a sua URL de retorno com o ID da sessão e o status anexados, para que seu app saiba o que aconteceu sem esperar por mais nada.
Com a sua marca, em planos elegíveis
O nome da sua empresa, o logotipo, a cor de destaque e os links de termos e de privacidade, aplicados à página hospedada e à página de verificação de credenciais.
Webhooks
Um callback assinado, assim que o resultado chega.
Informe uma URL de webhook ao criar uma sessão e enviaremos o resultado para ela assim que a sessão terminar, sem necessidade de polling.
Assinado, não apenas enviado
Toda entrega traz um cabeçalho X-Bio-Signature: um HMAC-SHA256 do corpo da requisição, para que você comprove que ela veio de nós antes de confiar nela.
Com novas tentativas, não é disparar e esquecer
Uma entrega que falha é repetida três vezes, com uma espera maior antes de cada tentativa.
Toda tentativa é registrada
Com sucesso ou falha, mantemos um registro da tentativa do nosso lado.
Em breve Um log de entregas dentro do portal, para você ver cada tentativa por conta própria, estará disponível em breve.
Trate o VERIFIED mais recente como a verdade
Com as novas tentativas, uma entrega pode, em casos raros, chegar fora de ordem. Não baseie sua lógica em receber um webhook — baseie-a no ID da sessão e deixe um VERIFIED posterior sobrescrever um anterior. Se você mantém seu próprio estado, remova duplicatas pelo ID da sessão, e não pelo recebimento do webhook.
Verifique a assinatura
Confie no payload antes de agir sobre ele.
Recalcule o HMAC-SHA256 sobre o corpo bruto da requisição e compare com X-Bio-Signature antes de fazer qualquer parsing.
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
O fluxo hospedado, inserido na sua própria página.
O widget cria uma sessão e renderiza o mesmo fluxo hospedado inline, em um iframe, para que os solicitantes nunca saiam do seu site.
- Renderiza em um iframe com acesso à câmera e ao microfone, dimensionado conforme o contêiner.
- Lê o status da sessão da mesma forma que a página hospedada: por meio da sua URL de retorno e do seu webhook, quando a sessão termina.
Em breve Os callbacks de conclusão na própria página (onComplete, onCancel, onStep, redimensionamento automático) chegarão em breve. Até lá, use return_url e webhooks para saber quando uma sessão termina — eles funcionam hoje.
Antes de levar isto para produção
Atualmente o widget aceita uma chave de API diretamente no navegador. Trate isso como uma conveniência do sandbox, não como um padrão para produção: crie a sessão a partir do seu próprio backend, mantendo a chave no lado do servidor, e entregue ao widget somente a sessão resultante, nunca uma chave ativa que o navegador de um visitante possa ler.
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>Página de verificação de credencial
Uma página pública para uma sessão verificada.
Quando uma sessão chega a VERIFIED, o link de verificação de credencial dela mostra uma confirmação em linguagem simples: o nome do candidato, o tipo de documento e o status. Qualquer pessoa com o link — um coobrigado, um recepcionista, uma contraparte — pode confirmar o resultado sem entrar no seu painel.
Jordan Reyes
Dados de exemploCarteira de motorista da Califórnia
Verificado
- Não é necessário fazer login para visualizá-la.
- Nenhuma imagem bruta de documento e nenhuma pontuação de confiança aparece nela — apenas um status e a identidade, nada mais.
- Com a mesma identidade visual da página hospedada, nos planos elegíveis.
Padrões de integração
Como seis tipos de negócio fazem essa integração.
Os blocos de construção são os mesmos em todo lugar: uma sessão, um link ou um widget, um webhook. O padrão ideal muda conforme como e quando você precisa da resposta.
Jurídico e escritórios de advocacia
Envie o link durante a triagem do cliente e guarde o recibo do webhook no dossiê, para que a identificação do cliente fique registrada antes de o contrato de honorários começar.
Condomínios e associações de proprietários (HOA)
Direcione a partir do formulário de cadastro de proprietário ou inquilino que o conselho já usa; o resultado chega antes de a unidade ser incluída no cadastro.
Fintech e crédito
O webhook aciona automaticamente a sua própria etapa de análise de crédito, de modo que o candidato nunca espere que uma pessoa perceba que um resultado chegou.
Marketplaces e plataformas gig
Incorpore o widget no onboarding de vendedores ou motoristas para um fluxo que nunca sai do seu app; crie a sessão a partir do seu backend, conforme recomendado acima.
E-signature
Execute o fluxo hospedado antes do início da cerimônia de assinatura e condicione a liberação dos documentos ao webhook, não à palavra do próprio solicitante.
Perguntas
Respostas diretas sobre a integração.
Comece agora
Configure um webhook. Veja-o disparar.
Crie uma sessão sandbox com uma URL de webhook, execute uma verificação no seu próprio celular e leia o callback assinado que ela envia.