---
title: "Webhooks"
description: "Digiploma webhooks: receive a POST when a document changes instead of polling the API, configured per organization and per institution."
canonical: "https://docs.lacunasoftware.com/en-us/articles/digiploma/api/webhooks"
locale: "en"
product: "Digiploma"
last_updated: "2026-10-11"
---

# Webhooks

Instead of polling the API, your application can receive **webhooks**: Digiploma sends a `POST` request to a URL of yours whenever a
document changes, for example when a diploma is concluded or annulled.

## Configure the webhook

There is one webhook URL for the organization, and optionally one per [institution](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/institutes):

* The **organization's webhook** receives the events of diplomas, emissions, registration requests, academic transcripts, curriculums and
  restamps. Configure it in the organization's **Configurações** (Settings) page, section **Integração**, which requires the
  **Administrador** role.
* The **institution's webhook** receives the events of its [lists of annulled diplomas](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/cancellation-lists) and
  [inspection files](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/inspection-files). Configure it on the institution's page, section **Integração**, or with
  `POST /api/institutes/{id}/integrations`. To send these events to the organization's webhook, turn on **Utilizar a configuração de webhook
  da organização** (`shouldUseSubscriptionWebhookSettings`). Until one of the two is configured, these events are not sent.

Either way, enable the webhook (**Habilitar webhooks**), enter the URL and choose how Digiploma authenticates to it:

| **Tipo de autenticação** (`authType`) | Header sent |
|---|---|
| `NoAuth` (**Sem autenticação**) | None. |
| `Basic` | `Authorization: Basic <token>`. The token must already be in Base64 (`user:password`). |
| `Bearer` | `Authorization: Bearer <token>`. Enter the token without the `Bearer` prefix. |
| `ApiKey` (**X-Api-Key**) | `X-Api-Key: <token>`. |

The token is the only way to authenticate the requests: they carry no signature. Use HTTPS, and a token that only Digiploma knows.

## The request

Each webhook is a `POST` with a JSON body, `Content-Type: application/json`, with the event type and the data of the item that changed:

```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"
  }
}
```

Respond with any `2xx` status to confirm the delivery; the response body is ignored. Any other status, an error or a timeout makes
Digiploma try again later, up to 10 more times over about four and a half hours.

## Handling webhooks

* **Treat a webhook as a notification**, and read the item with the API to get its current state. Webhooks are sent in the background,
  can arrive out of order, and can be repeated.
* The `type` and the `data` reflect the item **when the webhook is sent**, not when the change happened. When two changes are close
  together, you may receive the same type twice, or not receive the type of an intermediate status. For example, a transcript created and
  quickly signed may produce two `AcademicTranscriptConcluded` webhooks.
* Respond quickly, and process the event afterwards.
* There is no API to list past deliveries.

## Events

| `type` | `data` | When |
|---|---|---|
| `DegreeCreated` | Diploma | A diploma was created. |
| `DegreeConcluded` | Diploma | Both XML files of a diploma are signed. |
| `DegreeCanceled`, `DegreeCanceledTemporarily`, `DegreeRestored` | Diploma | A diploma was annulled, suspended or restored, with a reason. See [Issue and register](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/degrees#annul-suspend-or-restore-a-diploma). |
| `EmissionCreated`, `EmissionSigned`, `EmissionSentToRegistry`, `EmissionRegistered`, `EmissionCanceled` | Emission | See [Issue only](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/emissions#webhooks). |
| `EmissionRegistrationAccepted`, `EmissionRegistrationApproved`, `EmissionRegistrationRejected`, `EmissionRegistrationCanceled`, `EmissionRegistrationRegistered` | Emission and registration | The registrar changed the registration request of an emission. |
| `RegistrationCreated`, `RegistrationAccepted`, `RegistrationApproved`, `RegistrationRejected`, `RegistrationRegistered`, `RegistrationSigned`, `RegistrationCanceled` | Registration request | See [Register only](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/registrations#webhooks). |
| `AcademicTranscriptCreated`, `AcademicTranscriptConcluded`, `AcademicTranscriptCanceled`, `AcademicTranscriptCanceledTemporarily` | Academic transcript | See [Academic transcripts](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/academic-transcripts#webhooks). A restore is sent as `AcademicTranscriptConcluded`. |
| `CurriculumCreated`, `CurriculumConcluded`, `CurriculumCanceled` | Curriculum | See [Curriculums](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/curriculums#webhooks). |
| `CancellationListCreated`, `CancellationListSigned` | List of annulled diplomas | See [Lists of annulled diplomas](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/cancellation-lists#webhooks). Institution's webhook. |
| `InspectionFileCreated`, `InspectionFileSigned`, `InspectionFileGenerationError` | Inspection file | See [Inspection files](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/inspection-files#webhooks). Institution's webhook. |
| `RestampCreated`, `RestampUpdated`, `RestampApplied`, `RestampApplyingError` | Restamp | See [Restamps](https://docs.lacunasoftware.com/en-us/articles/digiploma/api/restamps#webhooks). Disabled unless the instance enables them. |

The API reference also lists `CancellationListGenerated`, `InspectionFileStarted`, `InspectionFileGenerated`,
`RegistrationSentToIssuer`, `EmissionAcceptedByRegistry` and `RestampCreationError`. Do not rely on them: they are obsolete, or are not sent
for the change their name suggests.

## Data of each event

The `data` models are in the API reference, under `Webhooks.*`. All carry the item's `id`, `creationDate` and `status`; most also
carry `updateDate` and the organization's id in `subscriptionId`.

| `data` | Fields |
|---|---|
| Diploma (`DegreeConcludedModel`, `DegreeUpdatedModel`) | `studentName`, `studentSocialName`, `studentCpf`, `course`, `issuingIes`, `registeringIes`, `verificationCode`, `version`. On status changes, also `reason` and `cancellationReason`. On creation, `academicTranscriptCreationError` when the transcript could not be generated. |
| Emission (`EmissionUpdatedModel`) | `studentName`, `studentSocialName`, `studentCpf`, `course`, `issuingIes`, `version`, `reason` and, once registered, `degreeId`. |
| Emission and registration (`EmissionRegistrationUpdatedModel`) | The emission's fields, plus `registrationStatus` and `registrationCancellationReason`. |
| Registration request (`RegistrationUpdatedModel`) | `studentName`, `studentCpf`, `course`, `issuingIes`, `description`, `version`, `reason`, `cancellationReason`. |
| Academic transcript (`AcademicTranscriptUpdatedModel`) | `studentName`, `studentSocialName`, `studentCpf`, `course`, `issuingIes`, `type`, `version`, `verificationCode`, `reason`. |
| Curriculum (`CurriculumUpdatedModel`) | `code`, `course`, `iesName`, `version`, `validationCode`, `reason`. |
| List of annulled diplomas (`CancellationListModel`) | `iesCode`, `iesName`, `sequenceNumber`, `version`, `maximumNextUpdateDate`, `signerDocumentId`, `signerDocumentUrl`. No `subscriptionId`. |
| Inspection file (`InspectionFileUpdatedModel`) | `type`, `iesCode`, `inspectedDegreesNumber`, `startDate`, `endDate`, `version`, `details`. No `subscriptionId`. |
| Restamp (`RestampUpdatedModel`) | `documentType`, `documentId`, `identifier`, `archivingExpiringDate`, `date`, `errorReason`. |