---
title: "Webhooks - Amplia Reg"
description: "Como cadastrar uma URL para receber webhooks do Amplia Reg a cada transição dos pedidos da sua aplicação: entrega, eventos e exemplos de payload."
canonical: "https://docs.lacunasoftware.com/articles/amplia-reg/integration/webhooks"
locale: "pt-BR"
product: "Amplia Reg"
last_updated: "2026-10-08"
---

# 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](https://docs.lacunasoftware.com/articles/amplia-reg/issuance#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](https://docs.lacunasoftware.com/articles/amplia-reg/issuance#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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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.

```json
{
  "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`.

```json
{
  "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

```json
{
  "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.

```json
{
  "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.

```json
{
  "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](https://docs.lacunasoftware.com/articles/amplia-reg/integration/cancel-order).

```json
{
  "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.

```json
{
  "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](https://docs.lacunasoftware.com/articles/amplia-reg/issuance)
* [Primeiros passos para integração](https://docs.lacunasoftware.com/articles/amplia-reg/integration/get-started)
* [Cancelamento de pedido](https://docs.lacunasoftware.com/articles/amplia-reg/integration/cancel-order)
* [Códigos de erro](https://docs.lacunasoftware.com/articles/amplia-reg/integration/error-codes)