Webhooks - Amplia Reg

Você pode cadastrar uma URL para ser chamada (método POST) a cada transição que acontecer com pedidos criados pela sua aplicação.

Veja Status do pedido para saber o que cada status significa e como um pedido passa de um para outro.

Entrega

O Amplia Reg envia cada notificação como uma requisição POST com corpo JSON (Content-Type: application/json). Só os pedidos criados pela sua aplicação geram notificações para ela. Responda com um código de status 2xx: qualquer outra resposta, ou a falta de resposta, conta como falha na entrega.

Se você configurar um segredo para o webhook, o Amplia Reg o envia em um header, conforme o tipo de autenticação escolhido:

Tipo de autenticação	Header enviado
Basic	Authorization: Basic <segredo>
Bearer	Authorization: Bearer <segredo>
ApiKey	X-Api-Key: <segredo>
CustomAuthorizationHeader	Authorization: <segredo>
Sem autenticação	(nenhum)

O segredo é enviado exatamente como foi configurado. Para Basic, configure como segredo a codificação Base64 de usuario:senha. Verifique o header em toda requisição para garantir que a notificação veio do Amplia Reg.

Eventos

O campo type indica de qual evento é a notificação:

type	Quando é enviado	Campo do payload
OrderStatusChanged	A cada mudança de status do pedido, inclusive na criação	orderStatusTransitionModel
OrderVideoIdentificationCompleted	Quando o titular conclui a vídeo identificação de um pedido do tipo vídeo identificação	videoIdentificationCompletedModel

O campo do payload do outro evento vem null.

Campos da mudança de status

Campo	Descrição
orderId	ID do pedido
orderNumber	Número do pedido
orderSaleNumber	Número do pedido no seu sistema de vendas, se informado na criação do pedido
previousStatus	Status antes da mudança; null na criação do pedido
status	Novo status. Veja Status do pedido
date	Data e hora da mudança
validationAgent, confirmationAgent	Agentes atribuídos ao pedido no momento da mudança (id, name, identifier, birthDate), ou null
description	Texto livre informado junto com a mudança: o motivo do cancelamento, a explicação do agente ao devolver ou recusar o pedido ou ao revogar o certificado, ou uma observação informada no envio ou na aprovação do pedido. null se não houver
pendencyReason	Quando status é Pending: por que o pedido foi devolvido. DataMismatch, TypingError, BadFiles, BryPSBioFraudSuspected, RedoSaf, RedoVideoconference ou Other
declineReason	Quando status é Declined: por que o pedido foi recusado. SubjectDataChanged, KeyGenFailed, ExpiredDocuments, OfficialDocumentsMismatch, ExtemporaneousQuery, BryPSBioFraud, BryPSBioDeleted, BryPSBioVideoconferenceEnroll, InternalAuditIrregularIssuance ou Other
revocationReason	Quando status é Revoked: por que o certificado foi revogado. RequestedBySubject, ViolationOrImproperUse, JudicialOrder, DeathOrExtinction, ActivityCessation, DiscoveryOfFalsityOrInaccuracyOfData, BryPSBioFraud, BryPSBioDeleted, InternalAuditIrregularIssuance, RevokedBySubject ou Other
reasonDesc	Rótulo curto do motivo, obrigatório quando o motivo é Other

Novos valores podem ser acrescentados a essas listas. Trate um valor desconhecido como Other.

Exemplos de payloads

observação

Os exemplos abaixo estão formatados apenas para facilitar a leitura; o JSON é enviado sem formatação. Todos os campos estão sempre presentes, com null quando não têm valor.

Pedido criado

{
  "type": "OrderStatusChanged",
  "orderStatusTransitionModel": {
    "orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
    "orderNumber": "800-005-520",
    "orderSaleNumber": null,
    "previousStatus": null,
    "status": "WaitingValidation",
    "date": "2025-03-18T15:26:11.704304+00:00",
    "validationAgent": null,
    "confirmationAgent": null,
    "description": null,
    "pendencyReason": null,
    "declineReason": null,
    "revocationReason": null,
    "reasonDesc": null
  },
  "videoIdentificationCompletedModel": null
}

Pedido em validação

{
  "type": "OrderStatusChanged",
  "orderStatusTransitionModel": {
    "orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
    "orderNumber": "800-005-520",
    "orderSaleNumber": null,
    "previousStatus": "WaitingValidation",
    "status": "InValidation",
    "date": "2025-03-18T15:27:28.358558+00:00",
    "validationAgent": {
      "id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
      "name": "John Doe",
      "identifier": "16545693050",
      "birthDate": "1988-04-01T00:00:00"
    },
    "confirmationAgent": null,
    "description": null,
    "pendencyReason": null,
    "declineReason": null,
    "revocationReason": null,
    "reasonDesc": null
  },
  "videoIdentificationCompletedModel": null
}

Pedido aguardando conferência

{
  "type": "OrderStatusChanged",
  "orderStatusTransitionModel": {
    "orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
    "orderNumber": "800-005-520",
    "orderSaleNumber": null,
    "previousStatus": "InValidation",
    "status": "WaitingConfirmation",
    "date": "2025-03-18T15:28:54.772066+00:00",
    "validationAgent": {
      "id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
      "name": "John Doe",
      "identifier": "16545693050",
      "birthDate": "1988-04-01T00:00:00"
    },
    "confirmationAgent": null,
    "description": null,
    "pendencyReason": null,
    "declineReason": null,
    "revocationReason": null,
    "reasonDesc": null
  },
  "videoIdentificationCompletedModel": null
}

Pedido em conferência

{
  "type": "OrderStatusChanged",
  "orderStatusTransitionModel": {
    "orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
    "orderNumber": "800-005-520",
    "orderSaleNumber": null,
    "previousStatus": "WaitingConfirmation",
    "status": "InConfirmation",
    "date": "2025-03-18T15:29:20.118344+00:00",
    "validationAgent": {
      "id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
      "name": "John Doe",
      "identifier": "16545693050",
      "birthDate": "1988-04-01T00:00:00"
    },
    "confirmationAgent": {
      "id": "5d2f8a41-93c7-4b0e-a1d6-2f7c9e3b8a10",
      "name": "Maria Silva",
      "identifier": "52998224725",
      "birthDate": "1990-07-12T00:00:00"
    },
    "description": null,
    "pendencyReason": null,
    "declineReason": null,
    "revocationReason": null,
    "reasonDesc": null
  },
  "videoIdentificationCompletedModel": null
}

Pedido devolvido para correção

O agente de conferência devolveu o pedido ao agente de validação. pendencyReason indica o motivo, e description traz a explicação do agente.

{
  "type": "OrderStatusChanged",
  "orderStatusTransitionModel": {
    "orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
    "orderNumber": "800-005-520",
    "orderSaleNumber": null,
    "previousStatus": "InConfirmation",
    "status": "Pending",
    "date": "2025-03-18T15:29:47.502913+00:00",
    "validationAgent": {
      "id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
      "name": "John Doe",
      "identifier": "16545693050",
      "birthDate": "1988-04-01T00:00:00"
    },
    "confirmationAgent": {
      "id": "5d2f8a41-93c7-4b0e-a1d6-2f7c9e3b8a10",
      "name": "Maria Silva",
      "identifier": "52998224725",
      "birthDate": "1990-07-12T00:00:00"
    },
    "description": "A foto do documento de identificação está ilegível. Envie-a novamente.",
    "pendencyReason": "BadFiles",
    "declineReason": null,
    "revocationReason": null,
    "reasonDesc": null
  },
  "videoIdentificationCompletedModel": null
}

Pedido aprovado (aguardando emissão)

Se a conferência não for exigida, o pedido vai de InValidation (ou WaitingResources) direto para WaitingIssue, e confirmationAgent vem null.

{
  "type": "OrderStatusChanged",
  "orderStatusTransitionModel": {
    "orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
    "orderNumber": "800-005-520",
    "orderSaleNumber": null,
    "previousStatus": "InConfirmation",
    "status": "WaitingIssue",
    "date": "2025-03-18T15:30:14.052941+00:00",
    "validationAgent": {
      "id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
      "name": "John Doe",
      "identifier": "16545693050",
      "birthDate": "1988-04-01T00:00:00"
    },
    "confirmationAgent": {
      "id": "5d2f8a41-93c7-4b0e-a1d6-2f7c9e3b8a10",
      "name": "Maria Silva",
      "identifier": "52998224725",
      "birthDate": "1990-07-12T00:00:00"
    },
    "description": null,
    "pendencyReason": null,
    "declineReason": null,
    "revocationReason": null,
    "reasonDesc": null
  },
  "videoIdentificationCompletedModel": null
}

Certificado emitido

{
  "type": "OrderStatusChanged",
  "orderStatusTransitionModel": {
    "orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
    "orderNumber": "800-005-520",
    "orderSaleNumber": null,
    "previousStatus": "WaitingIssue",
    "status": "Issued",
    "date": "2025-03-18T15:35:02.987120+00:00",
    "validationAgent": {
      "id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
      "name": "John Doe",
      "identifier": "16545693050",
      "birthDate": "1988-04-01T00:00:00"
    },
    "confirmationAgent": {
      "id": "5d2f8a41-93c7-4b0e-a1d6-2f7c9e3b8a10",
      "name": "Maria Silva",
      "identifier": "52998224725",
      "birthDate": "1990-07-12T00:00:00"
    },
    "description": null,
    "pendencyReason": null,
    "declineReason": null,
    "revocationReason": null,
    "reasonDesc": null
  },
  "videoIdentificationCompletedModel": null
}

Certificado revogado

revocationReason indica por que o certificado foi revogado, e description traz a explicação informada na revogação.

{
  "type": "OrderStatusChanged",
  "orderStatusTransitionModel": {
    "orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
    "orderNumber": "800-005-520",
    "orderSaleNumber": null,
    "previousStatus": "Issued",
    "status": "Revoked",
    "date": "2025-03-18T15:52:40.230571+00:00",
    "validationAgent": {
      "id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
      "name": "John Doe",
      "identifier": "16545693050",
      "birthDate": "1988-04-01T00:00:00"
    },
    "confirmationAgent": {
      "id": "5d2f8a41-93c7-4b0e-a1d6-2f7c9e3b8a10",
      "name": "Maria Silva",
      "identifier": "52998224725",
      "birthDate": "1990-07-12T00:00:00"
    },
    "description": "Revogação solicitada pelo titular.",
    "pendencyReason": null,
    "declineReason": null,
    "revocationReason": "RequestedBySubject",
    "reasonDesc": null
  },
  "videoIdentificationCompletedModel": null
}

Pedido recusado

declineReason indica por que o pedido foi recusado, e description traz a explicação do agente de conferência.

{
  "type": "OrderStatusChanged",
  "orderStatusTransitionModel": {
    "orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
    "orderNumber": "800-005-520",
    "orderSaleNumber": null,
    "previousStatus": "InConfirmation",
    "status": "Declined",
    "date": "2025-03-18T15:30:31.774102+00:00",
    "validationAgent": {
      "id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
      "name": "John Doe",
      "identifier": "16545693050",
      "birthDate": "1988-04-01T00:00:00"
    },
    "confirmationAgent": {
      "id": "5d2f8a41-93c7-4b0e-a1d6-2f7c9e3b8a10",
      "name": "Maria Silva",
      "identifier": "52998224725",
      "birthDate": "1990-07-12T00:00:00"
    },
    "description": "O documento de identificação do titular venceu antes da validação.",
    "pendencyReason": null,
    "declineReason": "ExpiredDocuments",
    "revocationReason": null,
    "reasonDesc": null
  },
  "videoIdentificationCompletedModel": null
}

Pedido cancelado

description traz o motivo enviado na requisição de cancelamento.

{
  "type": "OrderStatusChanged",
  "orderStatusTransitionModel": {
    "orderId": "0195a9dc-c0f0-4f5c-83d3-bf562ae98ed9",
    "orderNumber": "800-005-520",
    "orderSaleNumber": null,
    "previousStatus": "WaitingIssue",
    "status": "Canceled",
    "date": "2025-03-18T15:31:04.346843+00:00",
    "validationAgent": {
      "id": "0bcc8325-7122-4e5d-80b4-720beec03ede",
      "name": "John Doe",
      "identifier": "16545693050",
      "birthDate": "1988-04-01T00:00:00"
    },
    "confirmationAgent": {
      "id": "5d2f8a41-93c7-4b0e-a1d6-2f7c9e3b8a10",
      "name": "Maria Silva",
      "identifier": "52998224725",
      "birthDate": "1990-07-12T00:00:00"
    },
    "description": "Cancelamento solicitado pelo cliente",
    "pendencyReason": null,
    "declineReason": null,
    "revocationReason": null,
    "reasonDesc": null
  },
  "videoIdentificationCompletedModel": null
}

Vídeo identificação concluída

Enviado em pedidos do tipo vídeo identificação, quando o titular termina a gravação, junto com a notificação OrderStatusChanged da passagem do pedido para WaitingValidation. Os valores vêm do serviço de vídeo identificação: os abaixo são apenas ilustrativos.

{
  "type": "OrderVideoIdentificationCompleted",
  "orderStatusTransitionModel": null,
  "videoIdentificationCompletedModel": {
    "number": "800-005-520",
    "sessionId": "7c1e4b9a-2f3d-4e8a-9b6c-1d2e3f4a5b6c",
    "success": true,
    "faceLivenessStatus": {
      "provider": "<provider>",
      "success": true,
      "attemptCount": 1
    },
    "idCaptureStatus": {
      "success": true,
      "matchedFace": true,
      "matchedFaceLevel": 92
    },
    "recordingStatus": {
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "durationMs": 48210.0,
      "processed": true,
      "framesAnalyzedCount": 120,
      "framesAverageMatchLevel": 0.91,
      "framesAverageNormalizedMatchLevel": 0.88
    },
    "idCaptureFields": {
      "documentCountry": "BRA",
      "documentType": "<document type>",
      "fullName": "HOLDER NAME",
      "firstName": "HOLDER",
      "lastName": "NAME",
      "cpf": "07917307000",
      "dateOfBirth": "1995-10-15T00:00:00+00:00",
      "dateOfIssue": "2021-03-02T00:00:00+00:00",
      "dateOfExpiration": "2031-03-01T00:00:00+00:00"
    }
  }
}

Veja também

• Como funciona a emissão de certificados
• Primeiros passos para integração
• Cancelamento de pedido
• Códigos de erro