---
title: "Webhooks"
description: "Webhooks do Digiploma: como receber uma requisição POST quando um documento muda, em vez de fazer polling, na organização ou na instituição."
canonical: "https://docs.lacunasoftware.com/articles/digiploma/api/webhooks"
locale: "pt-BR"
product: "Digiploma"
last_updated: "2026-10-11"
---

# Webhooks

Em vez de consultar a API periodicamente (polling), sua aplicação pode receber **webhooks**: o Digiploma envia uma requisição `POST` para
uma URL sua sempre que um documento muda, por exemplo quando um diploma é concluído ou anulado.

## Configurar o webhook

Há uma URL de webhook para a organização e, opcionalmente, uma por [instituição](https://docs.lacunasoftware.com/articles/digiploma/api/institutes):

* O **webhook da organização** recebe os eventos de diplomas, emissões, requisições de registro, históricos escolares, currículos e
  renotarizações. Configure-o na página **Configurações** da organização, seção **Integração**, o que exige o papel **Administrador**.
* O **webhook da instituição** recebe os eventos das [listas de diplomas anulados](https://docs.lacunasoftware.com/articles/digiploma/api/cancellation-lists) e dos
  [arquivos de fiscalização](https://docs.lacunasoftware.com/articles/digiploma/api/inspection-files) da instituição. Configure-o na página da instituição, seção **Integração**, ou com
  `POST /api/institutes/{id}/integrations`. Para enviar esses eventos ao webhook da organização, ative **Utilizar a configuração de webhook
  da organização** (`shouldUseSubscriptionWebhookSettings`). Enquanto nenhum dos dois estiver configurado, esses eventos não são enviados.

Nos dois casos, habilite o webhook (**Habilitar webhooks**), informe a URL e escolha como o Digiploma se autentica nela:

| **Tipo de autenticação** (`authType`) | Header enviado |
|---|---|
| `NoAuth` (**Sem autenticação**) | Nenhum. |
| `Basic` | `Authorization: Basic <token>`. O token já precisa estar em Base64 (`user:password`). |
| `Bearer` | `Authorization: Bearer <token>`. Informe o token sem o prefixo `Bearer`. |
| `ApiKey` (**X-Api-Key**) | `X-Api-Key: <token>`. |

O token é a única forma de autenticar as requisições: elas não trazem assinatura. Use HTTPS e um token que só o Digiploma conheça.

## A requisição

Cada webhook é um `POST` com corpo JSON (`Content-Type: application/json`), com o tipo do evento e os dados do item que mudou:

```json
{
  "type": "DegreeConcluded",
  "data": {
    "id": "9b0f…",
    "subscriptionId": "4c1e…",
    "studentName": "Maria da Silva",
    "studentSocialName": null,
    "studentCpf": "12345678909",
    "course": "Administração",
    "issuingIes": "Universidade Exemplo",
    "registeringIes": "Universidade Exemplo",
    "creationDate": "2026-08-15T17:02:11+00:00",
    "updateDate": "2026-08-20T14:02:11+00:00",
    "status": "Active",
    "verificationCode": "1234.1234.3f9a0c1b2d4e",
    "version": "V105"
  }
}
```

Responda com qualquer status `2xx` para confirmar a entrega; o corpo da resposta é ignorado. Qualquer outro status, um erro ou um timeout
faz o Digiploma tentar de novo mais tarde, até mais 10 vezes, ao longo de cerca de quatro horas e meia.

## Como tratar os webhooks

* **Trate o webhook como uma notificação** e consulte o item pela API para obter o estado atual dele. Os webhooks são enviados em segundo
  plano, podem chegar fora de ordem e podem se repetir.
* Os campos `type` e `data` refletem o item **no momento em que o webhook é enviado**, não no momento da mudança. Quando duas mudanças
  acontecem em sequência rápida, você pode receber o mesmo tipo duas vezes, ou não receber o tipo de um status intermediário. Por exemplo,
  um histórico escolar criado e assinado logo em seguida pode gerar dois webhooks `AcademicTranscriptConcluded`.
* Responda rápido e processe o evento depois.
* Não há API para listar as entregas anteriores.

## Eventos

| `type` | `data` | Quando |
|---|---|---|
| `DegreeCreated` | Diploma | Um diploma foi criado. |
| `DegreeConcluded` | Diploma | Os dois arquivos XML de um diploma estão assinados. |
| `DegreeCanceled`, `DegreeCanceledTemporarily`, `DegreeRestored` | Diploma | Um diploma foi anulado, anulado temporariamente ou restaurado, com um motivo. Veja [Emissão e registro](https://docs.lacunasoftware.com/articles/digiploma/api/degrees#anular-ou-restaurar-um-diploma). |
| `EmissionCreated`, `EmissionSigned`, `EmissionSentToRegistry`, `EmissionRegistered`, `EmissionCanceled` | Emissão | Veja [Apenas emissão](https://docs.lacunasoftware.com/articles/digiploma/api/emissions#webhooks). |
| `EmissionRegistrationAccepted`, `EmissionRegistrationApproved`, `EmissionRegistrationRejected`, `EmissionRegistrationCanceled`, `EmissionRegistrationRegistered` | Emissão e registro | A registradora alterou a requisição de registro de uma emissão. |
| `RegistrationCreated`, `RegistrationAccepted`, `RegistrationApproved`, `RegistrationRejected`, `RegistrationRegistered`, `RegistrationSigned`, `RegistrationCanceled` | Requisição de registro | Veja [Apenas registro](https://docs.lacunasoftware.com/articles/digiploma/api/registrations#webhooks). |
| `AcademicTranscriptCreated`, `AcademicTranscriptConcluded`, `AcademicTranscriptCanceled`, `AcademicTranscriptCanceledTemporarily` | Histórico escolar | Veja [Históricos escolares](https://docs.lacunasoftware.com/articles/digiploma/api/academic-transcripts#webhooks). Uma restauração é enviada como `AcademicTranscriptConcluded`. |
| `CurriculumCreated`, `CurriculumConcluded`, `CurriculumCanceled` | Currículo | Veja [Currículos](https://docs.lacunasoftware.com/articles/digiploma/api/curriculums#webhooks). |
| `CancellationListCreated`, `CancellationListSigned` | Lista de diplomas anulados | Veja [Listas de diplomas anulados](https://docs.lacunasoftware.com/articles/digiploma/api/cancellation-lists#webhooks). Webhook da instituição. |
| `InspectionFileCreated`, `InspectionFileSigned`, `InspectionFileGenerationError` | Arquivo de fiscalização | Veja [Arquivos de fiscalização](https://docs.lacunasoftware.com/articles/digiploma/api/inspection-files#webhooks). Webhook da instituição. |
| `RestampCreated`, `RestampUpdated`, `RestampApplied`, `RestampApplyingError` | Renotarização | Veja [Renotarizações](https://docs.lacunasoftware.com/articles/digiploma/api/restamps#webhooks). Desabilitados, a menos que a instância os habilite. |

A referência da API também lista `CancellationListGenerated`, `InspectionFileStarted`, `InspectionFileGenerated`,
`RegistrationSentToIssuer`, `EmissionAcceptedByRegistry` e `RestampCreationError`. Não conte com eles: estão obsoletos ou não são
enviados na mudança que o nome sugere.

## Dados de cada evento

Os modelos de `data` estão na referência da API, em `Webhooks.*`. Todos trazem `id`, `creationDate` e `status` do item; a maioria
também traz `updateDate` e o id da organização em `subscriptionId`.

| `data` | Campos |
|---|---|
| Diploma (`DegreeConcludedModel`, `DegreeUpdatedModel`) | `studentName`, `studentSocialName`, `studentCpf`, `course`, `issuingIes`, `registeringIes`, `verificationCode`, `version`. Nas mudanças de status, também `reason` e `cancellationReason`. Na criação, `academicTranscriptCreationError`, quando o histórico escolar não pôde ser gerado. |
| Emissão (`EmissionUpdatedModel`) | `studentName`, `studentSocialName`, `studentCpf`, `course`, `issuingIes`, `version`, `reason` e, depois do registro, `degreeId`. |
| Emissão e registro (`EmissionRegistrationUpdatedModel`) | Os campos da emissão, mais `registrationStatus` e `registrationCancellationReason`. |
| Requisição de registro (`RegistrationUpdatedModel`) | `studentName`, `studentCpf`, `course`, `issuingIes`, `description`, `version`, `reason`, `cancellationReason`. |
| Histórico escolar (`AcademicTranscriptUpdatedModel`) | `studentName`, `studentSocialName`, `studentCpf`, `course`, `issuingIes`, `type`, `version`, `verificationCode`, `reason`. |
| Currículo (`CurriculumUpdatedModel`) | `code`, `course`, `iesName`, `version`, `validationCode`, `reason`. |
| Lista de diplomas anulados (`CancellationListModel`) | `iesCode`, `iesName`, `sequenceNumber`, `version`, `maximumNextUpdateDate`, `signerDocumentId`, `signerDocumentUrl`. Sem `subscriptionId`. |
| Arquivo de fiscalização (`InspectionFileUpdatedModel`) | `type`, `iesCode`, `inspectedDegreesNumber`, `startDate`, `endDate`, `version`, `details`. Sem `subscriptionId`. |
| Renotarização (`RestampUpdatedModel`) | `documentType`, `documentId`, `identifier`, `archivingExpiringDate`, `date`, `errorReason`. |