Primeiros passos
Na Auco, para dar a você controle total sobre a integração com cada processo criado, oferecemos um sistema de webhooks que permite receber notificações em cada etapa de cada fluxo de trabalho, do início ao fim.
Para configurar o webhook, há duas formas: pela API e pela plataforma web:
Criação a partir de app.auco.ai:
Você deve ser administrador ou ter permissões de administrador para fazer essa configuração. Pela plataforma, é possível criar apenas um webhook, que será o webhook 'default'.
- Faça login com seu e-mail e senha.
- Acesse seu perfil em www.auco.ai/profile
- Entre nas opções de desenvolvimento
- Na parte inferior, você encontrará as opções para modificar seu webhook e, se necessário, os cabeçalhos de autenticação.
Criação pela API da Auco
🆕 Sim! Pela API você pode criar vários webhooks. Cada webhook deve ter um id. Seu primeiro webhook deve ter o id 'default', para onde todas as notificações serão enviadas por padrão; os webhooks seguintes podem ter o id que você preferir.
Para definir quais webhooks receberão as notificações dos estados do processo, você deve salvar a lista de ids de webhooks durante a criação do documento.
Autenticação
Inclua sua chave privada no cabeçalho Authorization.
Authorization: prk_xxx...
Parâmetros de criação do webhook
| Nome | Tipo | Descrição |
|---|---|---|
id | String obrigatório | Nome identificador do webhook; o primeiro webhook deve ser default. |
description | String opcional | Descrição da finalidade do webhook. |
url | String obrigatório | URL (URI válida) para onde as notificações do webhook serão enviadas. |
header | Object opcional | Objeto { key, value } com o cabeçalho de autenticação a enviar. |
header.key | String condicional | Subcampo de header. Obrigatório se header for enviado: chave do cabeçalho. |
header.value | String condicional | Subcampo de header. Obrigatório se header for enviado: valor do cabeçalho. |
Onde são configurados?
Os webhooks são salvos por meio do endpoint Atualizar organização (PUT /v1.5/ext/company), no parâmetro webhooks. Lá você encontrará os exemplos completos de requisição em Curl, Python e Node.js.
👉 Veja Atualizar organização.
O parâmetro webhooks substitui a configuração existente: você deve enviar a lista completa e sempre incluir o webhook com id: "default". Para manter os webhooks já criados, inclua-os na requisição.
Sinais da proteção de identidade
Quando a validação de identidade de um signatário ou de um processo AucoFace passa pela proteção de identidade da Auco, a notificação inclui o campo signals: a lista de sinais antifraude que a proteção registrou nessa validação.
"signals": [
{ "code": "ALERT_FACE", "severity": "ALERT" },
{ "code": "ALERT_EMAIL_CHANGED", "severity": "INFO" }
]
severity | Significado | Interrompeu o processo |
|---|---|---|
REPORT | Correspondência com uma lista de bloqueio. | Sim |
ALERT | Alerta de fraude conforme a configuração da sua organização. | Sim |
INFO | Sinal informativo: foi registrado, mas não bloqueou o processo. | Não |
severity, não por codeA severidade dos códigos ALERT_* depende da configuração de cada organização: o mesmo código pode chegar como INFO ou como ALERT. Use severity para saber se o sinal bloqueou o processo.
signals vem nas notificações de assinatura (NOTIFICATION) e de bloqueio (BLOCKED) de documentos e pacotes, e em todas as notificações do AucoFace. Está ausente quando a validação nunca chegou à proteção —por exemplo, porque a comparação facial falhou antes— e quando a lista está vazia. Trate um code que você não reconhece como mais um sinal: novos códigos podem aparecer.
code | Significado |
|---|---|
REPORT | A pessoa está em uma lista de bloqueio. |
REPORT_EMAIL | O e-mail está em uma lista de bloqueio. |
REPORT_PHONE | O telefone está em uma lista de bloqueio. |
REPORT_FACE | O rosto está em uma lista de bloqueio. |
REPORT_DECEASED | O documento de identidade pertence a uma pessoa falecida. |
REPORT_FACE_MISMATCH | O rosto não corresponde ao cadastrado. |
ALERT_FACE | O rosto pertence a outra pessoa cadastrada. |
ALERT_IDENTITY_MISMATCH | Os dados não correspondem ao registro civil. |
ALERT_IDENTIFICATION_NOT_FOUND | O documento de identidade não existe no registro civil. |
ALERT_EMAIL_CHANGED | A pessoa usa um e-mail diferente do cadastrado. |
ALERT_PHONE_CHANGED | A pessoa usa um telefone diferente do cadastrado. |
ALERT_EMAIL | O e-mail já está associado a outra pessoa. |
ALERT_PHONE | O telefone já está associado a outra pessoa. |
ALERT_DEVICE | O dispositivo foi usado por várias pessoas. |
ALERT_IP | O IP foi usado por várias pessoas. |
ALERT_LOCATION | A localização é incomum para esta pessoa. |
Tempo de resposta e novas tentativas
A Auco espera no máximo 10 segundos pela resposta do seu endpoint. Se o seu servidor não responder dentro desse prazo, a Auco encerra a conexão e a notificação é registrada como timeout.
Esses 10 segundos cobrem toda a requisição: resolução de DNS, handshake TLS e o tempo que seu servidor leva para responder. Um endpoint que leva em média 8 segundos já está no limite.
Retorne 200 assim que receber a notificação e coloque o trabalho pesado —gravar no seu banco de dados, baixar o PDF, chamar outro serviço— em uma fila para execução em segundo plano.
Um handler que baixa arquivos ou chama um terceiro de forma síncrona antes de responder facilmente ultrapassa os 10 segundos, e a notificação é cortada mesmo que seu código tenha terminado corretamente.
Novas tentativas
Uma notificação é considerada entregue somente se o seu endpoint responder com um código 2xx. Se falhar —por timeout, ou porque você responde 4xx ou 5xx— a Auco a reenvia até 3 vezes, esperando um pouco mais a cada vez:
| Tentativa | Quando |
|---|---|
| 1ª | 2 minutos após a tentativa que falhou |
| 2ª | 4 minutos após a anterior |
| 3ª | 6 minutos após a anterior |
Após a terceira nova tentativa, a Auco deixa de tentar e essa notificação é descartada: ela não é enviada novamente.
4xx não cancela a notificaçãoResponder com um código de erro não diz à Auco para descartar o evento: isso aciona a mesma cadeia de novas tentativas de um timeout. Se a sua integração decidir ignorar um status, responda 200 mesmo assim e descarte-o do seu lado.
Uma nova tentativa repete a mesma notificação. Se o seu servidor a processou mas respondeu tarde, você a receberá novamente. Use o code do processo junto com o status para reconhecer uma repetição, em vez de criar um novo registro a cada entrega.
Como uma notificação descartada nunca é reenviada, não dependa apenas do webhook para saber em que ponto está um processo. Você pode consultar o estado dele quando precisar com Consultar processo.
⚠️ Respostas de erro
| Código | Descrição |
|---|---|
| 400 | Webhook default ausente |
| 401 | Autenticação inválida ou ausente |