Webhook

Nas mudanças relevantes de status enviamos um POST para a URL cadastrada da empresa.

Como funciona

Método: POST, corpo JSON, Content-Type: application/json.
Autenticação: enviamos Authorization: Bearer <token> com o token que a empresa nos forneceu.
Para habilitar, a empresa precisa nos disponibilizar a URL de envio e o Bearer Token.
Para receber novamente o estado atual de uma assinatura, use o reenvio de webhook.

Estrutura do payload

raiz
├── signatureUuid
├── signatureStatus
├── signaturePersons[]
│   ├── signaturePersonUuid
│   ├── signaturePersonStatus
│   ├── signatureUrl
│   ├── signaturePersonUnicoBiometricSelfieUrl
│   ├── signaturePersonDocument { documentType, frontDocumentUrl, backDocumentUrl, frontBackDocumentUrl }
│   ├── signaturePersonLatitude / Longitude / IpAddress / Device
│   └── parameters[]
│       ├── UNICO_BIOMETRIC    → biometricStatus, biometricScore
│       ├── UNICO_DOCUMENT     → documentStatus (normalmente vazio — ver tabela)
│       ├── SCOREHUB_DOCUMENT  → documentStatus
│       └── SCOREHUB_FACEMATCH → faceMatchStatus
└── signatureDocuments[]
    ├── signatureDocumentUuid
    ├── originalDocumentUrl
    └── signedDocumentUrl

Exemplos de recebimento

Documento físico (CNH)
Documento digital (PDF)

{
  "signatureUuid": "76dc8661-eb70-4a2e-aff8-704f3daba281",
  "signatureStatus": "FINISHED",
  "signaturePersons": [
    {
      "signaturePersonUuid": "c05548cd-4ddc-4ec4-b37f-9188d3af834d",
      "signaturePersonStatus": "FINISHED",
      "signatureUrl": "https://assinatura.dev.scorehub.com.br/assinar/....",
      "signaturePersonUnicoBiometricSelfieUrl": "https://scorehub-development.s3.amazonaws.com/.....",
      "signaturePersonDocument": {
        "documentType": "CNH",
        "frontDocumentUrl": "https://scorehub-development.s3.amazonaws.com/.....",
        "backDocumentUrl": "https://scorehub-development.s3.amazonaws.com/......"
      },
      "signaturePersonLatitude": "-25.45926592998089",
      "signaturePersonLongitude": "-49.242728657031726",
      "signaturePersonIpAddress": "187.7.145.44",
      "signaturePersonDevice": "iPhone iOS 18.7",
      "parameters": [
        {
          "parameterName": "UNICO_BIOMETRIC",
          "biometricStatus": "APPROVED",
          "biometricScore": ""
        },
        {
          "parameterName": "UNICO_DOCUMENT",
          "documentStatus": ""
        },
        {
          "parameterName": "SCOREHUB_DOCUMENT",
          "documentStatus": "APPROVED"
        },
        {
          "parameterName": "SCOREHUB_FACEMATCH",
          "faceMatchStatus": "APPROVED"
        }
      ]
    }
  ],
  "signatureDocuments": [
    {
      "signatureDocumentUuid": "21a0b8dd-6926-4d3c-92d0-44d830452fcf",
      "originalDocumentUrl": "https://scorehub-development.s3.amazonaws.com/....",
      "signedDocumentUrl": "https://scorehub-development.s3.amazonaws.com/......"
    }
  ]
}

{
  "signatureUuid": "12b1146f-68c0-4b88-b118-fe678c8cf5b6",
  "signatureStatus": "FINISHED",
  "signaturePersons": [
    {
      "signaturePersonUuid": "2c45f76d-2d76-4f15-adb7-4bd490693fc5",
      "signaturePersonStatus": "FINISHED",
      "signatureUrl": "https://assinatura.dev.scorehub.com.br/assinar/....",
      "signaturePersonUnicoBiometricSelfieUrl": "https://scorehub-development.s3.amazonaws.com/....",
      "signaturePersonDocument": {
        "documentType": "DIGITAL",
        "frontBackDocumentUrl": "https://scorehub-development.s3.amazonaws.com/....."
      },
      "signaturePersonLatitude": "-25.45926592998089",
      "signaturePersonLongitude": "-49.242728657031726",
      "signaturePersonIpAddress": "187.7.145.44",
      "signaturePersonDevice": "iPhone iOS 18.7",
      "parameters": [
        {
          "parameterName": "UNICO_BIOMETRIC",
          "biometricStatus": "APPROVED",
          "biometricScore": ""
        },
        {
          "parameterName": "UNICO_DOCUMENT",
          "documentStatus": ""
        },
        {
          "parameterName": "SCOREHUB_DOCUMENT",
          "documentStatus": "APPROVED"
        },
        {
          "parameterName": "SCOREHUB_FACEMATCH",
          "faceMatchStatus": "APPROVED"
        }
      ]
    }
  ],
  "signatureDocuments": [
    {
      "signatureDocumentUuid": "27f84921-f797-4690-b490-a95266b3c823",
      "originalDocumentUrl": "https://scorehub-development.s3.amazonaws.com/....",
      "signedDocumentUrl": "https://scorehub-development.s3.amazonaws.com/....."
    }
  ]
}

frontBackDocumentUrl

Quando o documento é DIGITAL (PDF), vem o campo frontBackDocumentUrl no lugar de frontDocumentUrl/backDocumentUrl. Caso esse campo venha preenchido, considere-o em vez de front/back.

Campos da assinatura

Bloco raiz do payload:

Campo	Descrição
`signatureUuid`	Identificador único da assinatura
`signatureStatus`	Status atual — valores possíveis
`signaturePersons`	Lista com os dados de cada signatário
`signatureDocuments`	Lista com os documentos da assinatura

Campos do signatário

Cada item de signaturePersons[]:

Campo	Descrição
`signaturePersonUuid`	Identificador único do signatário
`signaturePersonStatus`	Status do signatário — valores possíveis
`signatureUrl`	URL do artefato da assinatura
`signaturePersonUnicoBiometricSelfieUrl`	URL da selfie biométrica capturada
`signaturePersonDocument`	Documento de identificação capturado — ver abaixo
`signaturePersonLatitude` / `signaturePersonLongitude`	Local da assinatura
`signaturePersonIpAddress`	Endereço IP usado na assinatura
`signaturePersonDevice`	Identificação do dispositivo usado
`parameters`	Validações aplicadas ao signatário — detalhe

`signaturePersonDocument`

Campo	Descrição
`documentType`	Tipo do documento capturado — enum abaixo
`frontDocumentUrl`	Frente do documento
`backDocumentUrl`	Verso do documento
`frontBackDocumentUrl`	Documento único (tipo `DIGITAL`) — prioridade sobre front/back quando presente

Enum `documentType`

Valor	Documento
`RG`	Registro Geral (identidade)
`RG_NEW`	RG novo modelo
`CNH`	Carteira Nacional de Habilitação
`CNH_OPEN`	CNH aberta
`CIN`	Carteira de Identidade Nacional
`PASSPORT`	Passaporte
`CTPS`	Carteira de Trabalho
`RNE`	Registro Nacional de Estrangeiro
`DIGITAL`	Documento digital (PDF)

Campos do documento

Cada item de signatureDocuments[]:

Campo	Descrição
`signatureDocumentUuid`	Identificador único do documento
`originalDocumentUrl`	URL do documento original (sem assinatura)
`signedDocumentUrl`	URL do documento final já assinado

Parâmetros de validação

Lista parameters[] — validações aplicadas ao signatário. Cada item tem um parameterName que identifica o tipo. Os 4 parâmetros abaixo são sempre enviados:

Parâmetro	O que valida
`UNICO_BIOMETRIC`	Biometria facial (AntiFraude UNICO) — detalhe
`UNICO_DOCUMENT`	Normalmente vem com status vazio (`""`). Exceção: em reuso de biometria 1:1 com documento reaproveitado, vem `APPROVED_ONE_ONE`
`SCOREHUB_DOCUMENT`	Documento de identidade (captura e IA ScoreHub) — detalhe
`SCOREHUB_FACEMATCH`	Comparação facial selfie × documento — detalhe

UNICO_BIOMETRIC

Campo	Descrição
`biometricStatus`	Status da validação biométrica — enum abaixo
`biometricScore`	Pontuação numérica da biometria (como texto); vazio quando o plano não retorna SCORE

Enum `biometricStatus`

Valor	Significado
`APPROVED`	Biometria aprovada
`APPROVED_ONE_ONE`	Aprovada na comparação 1:1 (cliente já possuía biometria conosco)
`PENDING_UNICO`	Aguardando retorno da UNICO
`FRAUD`	Fraude identificada
`VALIDATION`	Em validação manual
`ERROR`	Erro no processamento
`RETRY`	Necessário repetir

SCOREHUB_DOCUMENT

Resultado consolidado da validação do documento de identidade.

Enum `documentStatus`

Valor	Significado
`APPROVED`	Documento aprovado
`REJECTED`	Documento rejeitado
`IN_PROGRESS`	Em andamento — inclui processamento, aguardando ação do signatário ou validação manual
`NOT_APPLICABLE`	Validação não se aplica — ocorre quando a biometria terminou em erro

SCOREHUB_FACEMATCH

Comparação facial entre a selfie e a foto do documento.

Enum `faceMatchStatus`

Valor	Significado
`NOT_APPLICABLE`	Comparação facial não habilitada para essa assinatura
`IN_PROGRESS`	Ainda processando ou sem resultado disponível
`APPROVED`	Comparação aprovada — todas as faces conferem
`REJECTED`	Comparação rejeitada — alguma face não confere

Como funciona​

Estrutura do payload​

Exemplos de recebimento​

Campos da assinatura​

Campos do signatário​

signaturePersonDocument​

Enum documentType​

Campos do documento​

Parâmetros de validação​

UNICO_BIOMETRIC​

Enum biometricStatus​

SCOREHUB_DOCUMENT​

Enum documentStatus​

SCOREHUB_FACEMATCH​

Enum faceMatchStatus​