Integration API webhooks

A webhook is an automatic notice Eduvem sends to another system the moment something happens - with no need for that system to keep asking “so, did anything change?” With webhooks, when a Participant’s enrollment changes status, they receive a certificate, or they complete a track, Eduvem “pushes” that information right away to the address your integration team provides (HR, a BI tool, an internal system).

It’s the “real-time” alternative to polling: instead of your system asking every so often what changed, Eduvem tells you on its own the moment it changes.

Who this feature is for

Setting up webhooks involves two people with different roles:

• The institution administrator (you) releases the permission on an API token. That’s what this article covers.
• Your integration team (whoever writes the code) uses that token to register the addresses that will receive the notices and to handle each notice received. That technical part is in the API documentation.

Releasing webhook permission on a token

Webhooks are managed with the same API tokens used by the rest of the integration - there is no separate credential. The ability to manage webhooks sits behind a specific permission, which comes off by default: webhooks:manage.

1. In the admin panel, open the institution’s Integrations tab.
2. Create a new API token (see Integration API tokens). If the integration already has a token, you can also turn the permission on for it with the Edit permissions button in the token list, without creating a new token.
3. In the token’s list of permissions (scopes), check Webhooks (manage) and Reports (read) - subscribing to any event requires both permissions together.
4. Confirm with OK and copy the token value shown - it will not be displayed again.

A token without the Webhooks permission that tries to manage webhooks gets an access refusal. Creating or updating a subscription also requires the Reports (read) permission together with Webhooks - without it, the call is refused even with Webhooks checked; listing, testing and deleting subscriptions do not require Reports. Granting a token permission to read participants and enrollments does not, by itself, grant webhook permission - it needs to be checked explicitly. As always, grant a token only what the integration actually uses.

Notices are bound to the token that last created or updated the webhook registration. If you remove the Reports (read) permission from that token, or delete it, its webhooks stop sending notices and show up as tokenRevoked; events from that period are not resent afterwards. To resume, the integration team must reactivate the webhook using a token that holds both permissions. When replacing a token, create the new one, reactivate each webhook with it, and only then delete the old one.

What the notices carry (overview)

Each notice is a signed notification, sent to the address your team registers, reporting the event (for example, “enrollment status change”, “certificate issued” or “track completed”) and the related data: the enrollment, the class, the content and the participant. A track-completed notice is different: it carries the participant and the track (identifier and name), with no enrollment, class or content - a track brings several classes together, so the notice isn’t tied to a single one. Everything is isolated per institution - a notice only carries data for the institution that owns the token.

Sending the CPF inside the notice follows your institution’s profile configuration: if the CPF field isn’t enabled in the profile, it isn’t sent.

When the person has an externalId (the HR system code loaded through people sync), the notice’s person block also carries person.externalId; without it, the key does not appear and the notice stays as before. See API documentation.

Technical details live in the API documentation

Registering the addresses that receive the notices, the full event catalog, verifying the security signature, the retry policy and monitoring deliveries are all done by the integration team and are described in the API documentation. Forward that material to whoever will code the integration.

See also

• Tracks
• Integration API tokens
• API documentation