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:

• 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 and 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:

{
  "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.
EmissionCreated, EmissionSigned, EmissionSentToRegistry, EmissionRegistered, EmissionCanceled	Emission	See Issue only.
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.
AcademicTranscriptCreated, AcademicTranscriptConcluded, AcademicTranscriptCanceled, AcademicTranscriptCanceledTemporarily	Academic transcript	See Academic transcripts. A restore is sent as AcademicTranscriptConcluded.
CurriculumCreated, CurriculumConcluded, CurriculumCanceled	Curriculum	See Curriculums.
CancellationListCreated, CancellationListSigned	List of annulled diplomas	See Lists of annulled diplomas. Institution's webhook.
InspectionFileCreated, InspectionFileSigned, InspectionFileGenerationError	Inspection file	See Inspection files. Institution's webhook.
RestampCreated, RestampUpdated, RestampApplied, RestampApplyingError	Restamp	See Restamps. 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.