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:

• 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 e dos arquivos de fiscalização 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:

{
  "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.
EmissionCreated, EmissionSigned, EmissionSentToRegistry, EmissionRegistered, EmissionCanceled	Emissão	Veja Apenas emissão.
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.
AcademicTranscriptCreated, AcademicTranscriptConcluded, AcademicTranscriptCanceled, AcademicTranscriptCanceledTemporarily	Histórico escolar	Veja Históricos escolares. Uma restauração é enviada como AcademicTranscriptConcluded.
CurriculumCreated, CurriculumConcluded, CurriculumCanceled	Currículo	Veja Currículos.
CancellationListCreated, CancellationListSigned	Lista de diplomas anulados	Veja Listas de diplomas anulados. Webhook da instituição.
InspectionFileCreated, InspectionFileSigned, InspectionFileGenerationError	Arquivo de fiscalização	Veja Arquivos de fiscalização. Webhook da instituição.
RestampCreated, RestampUpdated, RestampApplied, RestampApplyingError	Renotarização	Veja Renotarizações. 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.