Webhooks
Learn about Edusign webhooks, authentication methods, timezone handling, and how to secure your webhook endpoints with Client Secret and HMAC verification.
What is a webhook ?
A webhook is a method used in web development that allows one application to provide real-time information to another application over HTTP, it's essentially a way for apps to communicate with each other automatically.
When an event occurs in the source app, a notification is sent out as an HTTP POST request to a specified URL - this is the webhook URL.
This request carries a payload with information about the event that has occurred.
The receiving application, which has been configured to listen for such notifications at the given URL, can then take immediate action based on the transmitted data.
It's a simple, efficient, and server-friendly way for applications to extend their functionality and integrate with external services without the need for constant polling.
Authentication & Security Keys
Before diving into webhook security, it's important to understand the different types of authentication credentials in Edusign:
API Keys vs Client Secret
API Keys are used for general API authentication when making requests to Edusign's API endpoints. You can have up to 5 API keys per school, and they're used with the Authorization: Bearer <API_KEY> header.
Client Secret is specifically tied to Edusign Apps and is used for webhook signature verification. Here's how they differ:
| Feature | API Keys | Client Secret |
|---|---|---|
| Purpose | General API authentication | Webhook HMAC signature verification |
| Quantity | Up to 5 per school | 1 per app |
| Usage | Authorization: Bearer <API_KEY> | HMAC signature validation |
| Scope | All API endpoints | Webhook security only |
Creating an Edusign App
To obtain a Client ID and Client Secret, you need to create an Edusign App:
- Go to your school dashboard: Private Apps
- Create a new app (can remain private or be published publicly after validation)
- Your app will provide you with:
- Client ID: Public identifier for your app
- Client Secret: Private key used for webhook HMAC verification
- API Key: For making API requests (same as regular API keys)
Key Difference: While you can have multiple API keys for general API access, the Client Secret is app-specific and is specifically used for verifying webhook signatures.
Need help creating an app? Check out our detailed guide: Building an App for step-by-step instructions.
Event list
You can find the list of all the available webhook events in the Webhook payloads reference section below.
We will update and add more events in the upcoming months.
Auto retry
- Webhooks are sent as HTTP
POSTrequests with a JSON body, and time out after 15 seconds. - Your endpoint must answer with a
2xxstatus code. Any other status code, a timeout or a connection error counts as a failed delivery. - A failed delivery is retried automatically a few minutes later, up to 3 attempts in total.
- If the last attempt fails, the webhook is dropped. For webhooks configured by the school, Edusign then sends a notification to the school's administrators in the dashboard.
The same webhook can be delivered more than once. For example, when your endpoint processes a request but answers after the 15-second timeout, the delivery is retried. Webhooks carry no unique delivery identifier: make your processing idempotent, and answer quickly โ run heavy processing asynchronously.
Date and Time Format in Webhooks
Webhook payloads contain two kinds of date values, which use different timezones and formats:
- Course and absence dates are expressed in your school's configured timezone, without any timezone offset.
- Event timestamps (when a signature or a survey answer happened) are expressed in UTC, in ISO 8601.
| Field | Events | Timezone | Format | Example |
|---|---|---|---|---|
course.START, course.END | on_student_sign, on_teacher_sign | School's timezone | YYYY-MM-DD HH:mm:ss | 2026-03-26 09:00:00 |
absence.START, absence.END | on_justified_absence | School's timezone | YYYY/MM/DD HH:mm:ss | 2026/03/26 09:00:00 |
absence.REQUEST_DATE | on_justified_absence | School's timezone | YYYY-MM-DD HH:mm:ss | 2026-03-25 14:00:00 |
signature.timestamp | on_student_sign, on_teacher_sign | UTC | ISO 8601 | 2026-03-26T08:15:00+00:00 |
submittedAt | on_survey_answer | UTC | ISO 8601, with milliseconds | 2026-03-26T08:15:00.000Z |
Example: if your school is configured with the Paris timezone,
"START": "2026-03-26 09:00:00"means 9:00 in Paris, and a signature made at 9:15 in Paris is sent as"timestamp": "2026-03-26T08:15:00+00:00".
Webhook security
HMAC Signature Verification
Important: HMAC signature verification only works with apps from the Edusign app marketplace. If you haven't created an Edusign App yet, please refer to the Authentication & Security Keys section above.
Webhook HMAC is a security technique where both the sender (Edusign) and receiver (your application) share a secret key - the Client Secret from your Edusign App.
When Edusign sends a webhook, it creates a unique HMAC signature using:
- Your app's Client Secret
- The webhook message content
The signature is sent in the x-edusign-hmac header. It is the HMAC-SHA256 of the raw request body, keyed with your app's Client Secret and encoded in hexadecimal. Your application should:
- Retrieve the HMAC signature from the
x-edusign-hmacheader - Compute the HMAC-SHA256 of the raw request body โ as received, before any JSON parsing โ with your app's Client Secret
- Compare both signatures to verify authenticity
Which Client Secret is Used?
When you have multiple API keys but only one app with webhooks configured, Edusign uses the Client Secret from the specific app that has the webhook configured. This ensures each app has its own unique signature verification.
Why not API Keys? API Keys are designed for authentication when making requests TO Edusign's API. Client Secrets are specifically designed for verifying that requests are FROM Edusign to your application.
Edusign libraryYou can also use the Edusign library to retrieve the HMAC and compare it with the Client Secret of your app.
You can retrieve our library here.
Example Verification Process
// Get the signature from the webhook headers
const signature = req.headers['x-edusign-hmac'];
// Your app's Client Secret (not API Key)
const clientSecret = 'your-app-client-secret';
// Verify the webhook authenticity
try {
// Use Edusign library or implement your own HMAC verification
const isValid = verifyEdusignWebhook(req.body, signature, clientSecret);
if (isValid) {
// Process the webhook safely
console.log('Webhook verified successfully');
} else {
// Reject invalid webhook
return res.status(401).json({ error: 'Invalid signature' });
}
} catch (error) {
return res.status(401).json({ error: 'Verification failed' });
}Generating Webhooks
Webhooks can be generated and managed directly within the Edusign admin settings page. Navigate to the "Settings" section in your Edusign admin dashboard, then select "Webhooks" to configure and generate new webhooks for your applications.
You can also manage them through the API with the /v3/webhooks endpoints: create, list, update and delete a webhook. Through the API, the URL must use https, and local or private network addresses are rejected. on_course_unlocked can only be subscribed to through the API.
Important: Make sure to use the Client Secret from your Edusign App (not your API Key) for webhook HMAC verification. The Client Secret is specifically designed for this security purpose.
Quick Start Checklist
To set up webhooks securely:
- โ Create an Edusign App
- โ Note your Client Secret (for HMAC verification)
- โ Note your API Key (for making API requests)
- โ Configure your webhook endpoint URL in Edusign settings or through the API
- โ Implement HMAC verification using your Client Secret
- โ Make your processing idempotent โ a delivery can be retried (see Auto retry)
- โ Test your webhook with a sample event
Webhook payloads reference
Every webhook is sent as a POST request to your registered URL. Every payload contains the type field, followed by the fields of the event. Webhooks sent on behalf of a marketplace app also contain appId:
{
"type": "on_student_created",
"appId": "app-marketplace-id",
"studentId": "student-uuid"
}This reference covers every event you can subscribe to, in the webhook settings or through the API.
| Field | Type | Description |
|---|---|---|
| type | string | The webhook event type (see the sections below) |
| appId | string | The App Marketplace ID. Only present when the webhook is sent on behalf of a marketplace app: school-level webhooks do not include this field, it is never sent as null. |
Missing values. When a value is not available, the fields of most events are sent as an empty string "" (for example API_ID, ATTENDANCE_LIST_GENERATED, DOCUMENT_URL, pdfUrl), and nested objects as {}. Fields described as optional under an event are omitted from the body instead.
HTTP headers
Webhooks are sent with these headers:
| Header | Description |
|---|---|
| Content-Type | application/json |
| User-Agent | Edusign-Webhook/1.0 |
| x-edusign-webhook-type | The event type (e.g. on_student_sign) |
| x-edusign-school-id | The ID of the school the event belongs to |
| x-edusign-lang | Language code of the school (default: fr) |
| x-edusign-app-id | The App Marketplace ID โ app webhooks only, absent for school webhooks |
| x-edusign-hmac | HMAC-SHA256 signature of the body โ app webhooks only, absent for school webhooks |
| x-edusign-client-id | App client ID โ app webhooks only, absent for school webhooks |
Students
on_student_sign
Fired when a student signs an attendance sheet.
{
"type": "on_student_sign",
"student": {
"FIRSTNAME": "Jean",
"LASTNAME": "Dupont",
"EMAIL": "[email protected]",
"ID": "student-uuid",
"API_ID": "external-api-id"
},
"course": {
"ID": "course-uuid",
"NAME": "Mathematics 101",
"START": "2026-03-26 09:00:00",
"END": "2026-03-26 12:00:00",
"API_ID": "external-api-id"
},
"signature": {
"state": true,
"timestamp": "2026-03-26T08:15:00+00:00"
}
}course.START and course.END are in the school's timezone, signature.timestamp is in UTC โ see Date and Time Format in Webhooks. API_ID is "" when not set.
on_student_created
Fired when a student is created.
{
"type": "on_student_created",
"studentId": "student-uuid"
}on_student_edited
Fired when a student record is modified.
{
"type": "on_student_edited",
"studentId": "student-uuid"
}on_student_deleted
Fired when a student is deleted.
{
"type": "on_student_deleted",
"studentId": "student-uuid"
}on_student_unremoved
Fired when a deleted student is restored.
{
"type": "on_student_unremoved",
"studentId": "student-uuid"
}on_student_archived
Fired when a student is archived.
{
"type": "on_student_archived",
"studentId": "student-uuid"
}on_student_unarchived
Fired when an archived student is restored.
{
"type": "on_student_unarchived",
"studentId": "student-uuid"
}on_student_excluded_from_course
Fired when a student is excluded from a course.
{
"type": "on_student_excluded_from_course",
"studentId": "student-uuid",
"courseId": "course-uuid"
}Teachers
on_teacher_sign
Fired when a teacher signs an attendance sheet.
{
"type": "on_teacher_sign",
"teacher": {
"FIRSTNAME": "Marie",
"LASTNAME": "Martin",
"EMAIL": "[email protected]",
"ID": "teacher-uuid",
"API_ID": "external-api-id"
},
"course": {
"ID": "course-uuid",
"NAME": "Mathematics 101",
"START": "2026-03-26 09:00:00",
"END": "2026-03-26 12:00:00",
"API_ID": "external-api-id"
},
"signature": {
"state": true,
"timestamp": "2026-03-26T08:05:00+00:00"
}
}Same date formats as on_student_sign.
on_teacher_created
Fired when a teacher is created.
{
"type": "on_teacher_created",
"teacherId": "teacher-uuid"
}on_teacher_edited
Fired when a teacher record is modified.
{
"type": "on_teacher_edited",
"teacherId": "teacher-uuid"
}on_teacher_deleted
Fired when a teacher is deleted.
{
"type": "on_teacher_deleted",
"teacherId": "teacher-uuid"
}on_teacher_unremoved
Fired when a deleted teacher is restored.
{
"type": "on_teacher_unremoved",
"teacherId": "teacher-uuid"
}Groups
on_group_created
Fired when a group is created.
{
"type": "on_group_created",
"groupId": "group-uuid"
}on_group_edited
Fired when a group is modified.
{
"type": "on_group_edited",
"groupId": "group-uuid"
}on_group_deleted
Fired when a group is deleted.
{
"type": "on_group_deleted",
"groupId": "group-uuid"
}on_group_unremoved
Fired when a deleted group is restored.
{
"type": "on_group_unremoved",
"groupId": "group-uuid"
}Courses
on_course_created
Fired when a course is created.
{
"type": "on_course_created",
"courseId": "course-uuid"
}on_course_edited
Fired when a course is modified.
{
"type": "on_course_edited",
"courseId": "course-uuid"
}on_course_deleted
Fired when a course is deleted.
{
"type": "on_course_deleted",
"courseId": "course-uuid"
}on_course_locked
Fired when a course is locked (attendance sheet generated/archived).
{
"type": "on_course_locked",
"courseId": "course-uuid",
"ATTENDANCE_LIST_GENERATED": "https://s3.amazonaws.com/..."
}on_course_start (scheduled)
Fired when a course's scheduled start time arrives.
{
"type": "on_course_start",
"courseId": "course-uuid"
}on_course_end (scheduled)
Fired when a course's scheduled end time arrives.
{
"type": "on_course_end",
"courseId": "course-uuid"
}on_course_unlocked
Fired when a locked course is unlocked.
{
"type": "on_course_unlocked",
"courseId": "course-uuid"
}This event is not offered in the webhook settings of the dashboard: subscribe to it through the API.
Trainings
on_training_started (scheduled)
Fired when a training's scheduled start date arrives.
{
"type": "on_training_started",
"trainingId": "training-uuid"
}on_training_ended (scheduled)
Fired when a training's scheduled end date arrives.
{
"type": "on_training_ended",
"trainingId": "training-uuid"
}on_training_archived
Fired when a training is archived through the API v3 (DELETE /v3/trainings/...). Archiving a training from the Edusign dashboard does not fire this webhook.
{
"type": "on_training_archived",
"trainingId": "training-uuid"
}Each course locked by the archive also fires its own on_course_locked webhook.
Documents
on_document_completed
Fired when a document finishes signing/generation.
{
"type": "on_document_completed",
"documentId": "document-uuid",
"DOCUMENT_URL": "https://s3.amazonaws.com/.../document.pdf",
"DOCUMENT_PROOF_URL": "https://s3.amazonaws.com/.../proof.pdf"
}on_document_participant_signed
Fired when a participant signs a document.
{
"type": "on_document_participant_signed",
"documentId": "document-uuid",
"participant": {
"type": "STUDENT",
"id": "participant-uuid"
}
}The participant.type field can be "ADMIN", "STUDENT", or "TEACHER".
on_document_sent
Fired each time a document is sent to a recipient, whether it requires a signature or not. withSignature tells which.
{
"type": "on_document_sent",
"documentId": "document-uuid",
"recipientId": "recipient-uuid",
"recipientType": "student",
"withSignature": true
}recipientType is student, professor or external.
on_document_with_signature_sent
Fired when a document requiring a signature is sent to a recipient.
{
"type": "on_document_with_signature_sent",
"documentId": "document-uuid",
"recipientId": "recipient-uuid",
"recipientType": "student"
}on_document_without_signature_sent
Fired when a document that does not require a signature is sent to a recipient. These documents are only sent to students.
{
"type": "on_document_without_signature_sent",
"documentId": "document-uuid",
"recipientId": "recipient-uuid",
"recipientType": "student"
}Each sending fires both on_document_sent and one of on_document_with_signature_sent / on_document_without_signature_sent. Subscribe to on_document_sent to receive every sending, or to one of the two others to receive only that kind of document: subscribing to on_document_sent and to a variant gives you two webhooks for the same sending.
on_document_refused
Fired when a recipient refuses to sign a document.
{
"type": "on_document_refused",
"documentId": "document-uuid",
"recipientId": "recipient-uuid",
"recipientType": "student",
"reason": "Reason given by the recipient"
}Optional fields: recipientType is omitted when the recipient's type cannot be determined, and reason when the recipient gave none.
on_document_expired (scheduled)
Fired when a document is still not completed at its expiration date.
{
"type": "on_document_expired",
"documentId": "document-uuid"
}Surveys
on_survey_answer
Fired when a recipient answers a survey or a quiz.
{
"type": "on_survey_answer",
"surveyId": "survey-uuid",
"recipientId": "student-uuid",
"recipientType": "student",
"studentId": "student-uuid",
"surveyType": "survey",
"isAnonymous": false,
"submittedAt": "2026-03-26T08:15:00.000Z",
"nbQuestions": 2,
"responses": [
{
"questionId": "satisfaction",
"type": "rating",
"value": 4,
"skipped": false
},
{
"questionId": "comment",
"type": "comment",
"skipped": true
}
]
}| Field | Description |
|---|---|
| surveyId | ID of the survey |
| recipientId | ID of the respondent โ the string anonymous on an anonymous survey |
| recipientType | student, professor or external |
| studentId / professorId / externalId | ID of the respondent. Only one of the three is sent, the one matching recipientType โ anonymous on an anonymous survey |
| surveyType | survey or quiz |
| isAnonymous | true for an anonymous survey |
| submittedAt | When the answer was submitted, in UTC (ISO 8601) |
| nbQuestions | Number of questions in the survey โ one item per question in responses |
| nbCorrectAnswers | Number of correct answers. Optional: only sent when surveyType is quiz |
| responses | One item per question: questionId (the question name in the survey), type (the question type, e.g. radiogroup, checkbox, rating, text, comment), value and skipped |
The type of value depends on the question type: a string, a number, a boolean, an array or an object. value is omitted when the question was skipped.
on_survey_sent
Fired when a survey is sent to a recipient, including each recipient of a scheduled sending.
{
"type": "on_survey_sent",
"surveyId": "survey-uuid",
"recipientId": "recipient-uuid",
"recipientType": "student"
}recipientType is student, professor or external. On an anonymous survey, recipientId is the string anonymous.
on_scheduled_survey_sent
Fired once when a scheduled survey has been sent automatically, in addition to the on_survey_sent webhook of each recipient.
{
"type": "on_scheduled_survey_sent",
"surveyId": "survey-uuid",
"courseId": "course-uuid",
"recipientIds": [
"recipient-uuid"
],
"recipientCount": 1
}Optional fields: courseId is present when the survey is attached to a course, trainingId when it is attached to a training. On an anonymous survey, recipientIds contains the string anonymous for each recipient.
Absences
on_justified_absence
Fired when an absence is justified.
{
"type": "on_justified_absence",
"absence": {
"ID": "absence-uuid",
"STUDENT_ID": "student-uuid",
"TYPE": 1,
"COMMENT": "Medical appointment",
"FILE_URL": "https://...",
"API_ID": "external-api-id",
"API_TYPE": "connector-name",
"COURSE_ID": "course-uuid",
"SCHOOL_ID": "school-uuid",
"START": "2026/03/26 09:00:00",
"END": "2026/03/26 12:00:00",
"REQUEST_DATE": "2026-03-25 14:00:00"
}
}The absence object contains these 12 fields. Values that are not set are sent as "" (0 for TYPE). START, END and REQUEST_DATE are in the school's timezone, with different formats โ see Date and Time Format in Webhooks.
on_request_justified_absence
Fired when a student requests an absence justification.
{
"type": "on_request_justified_absence",
"absenceRequest": {
"ID": "absence-request-uuid",
"TYPE": 1,
"STUDENT_ID": "student-uuid",
"SCHOOL_ID": "school-uuid",
"FILE_URL": "https://...",
"STATUS": 0,
"COMMENT": "Doctor visit",
"DATE_CREATED": "2026-03-26T10:00:00+02:00",
"START": "2026-03-26T09:00:00+02:00",
"END": "2026-03-26T12:00:00+02:00"
}
}Note the field is absenceRequest (not absence). The object contains all absence request fields except FILE, fileType, and rgpdChecked which are stripped before sending.
on_abscence_report_generated
Fired when an absence report PDF is generated.
{
"type": "on_abscence_report_generated",
"studentId": "student-uuid",
"externalId": "external-recipient-id",
"pdfUrl": "https://s3.amazonaws.com/.../report.pdf"
}Email
on_email_invalid
Fired when an email address is detected as invalid (bounce/spam).
{
"type": "on_email_invalid",
"email": "[email protected]",
"invalid_type": "hard",
"invalid_reason": "bounce"
}Zoom
on_zoom_meeting_created
Fired when a Zoom meeting is created for a course.
{
"type": "on_zoom_meeting_created",
"COURSE_ID": "course-uuid",
"meeting": {
"ID": "zoom-meeting-id",
"URL": "https://zoom.us/j/123456",
"START": "2026-03-26T09:00:00+02:00",
"END": "2026-03-26T12:00:00+02:00"
}
}Note: this webhook uses COURSE_ID (uppercase) instead of courseId.
App Marketplace
on_app_parameters_changed
Fired when an app's configuration parameters are changed.
{
"type": "on_app_parameters_changed",
"appId": "app-marketplace-uuid",
"parameters": {
"customParam1": "value1",
"customParam2": true
}
}The parameters object contains the app's custom configuration as key-value pairs.
cron_midnight
Automatically fired every day at 00:07 UTC. Allows apps to have a daily cron trigger from Edusign.
{
"type": "cron_midnight"
}Summary table
| Event | Type string | Key payload fields |
|---|---|---|
| Student signs | on_student_sign | student, course, signature |
| Student created | on_student_created | studentId |
| Student edited | on_student_edited | studentId |
| Student deleted | on_student_deleted | studentId |
| Student restored | on_student_unremoved | studentId |
| Student archived | on_student_archived | studentId |
| Student unarchived | on_student_unarchived | studentId |
| Student excluded from course | on_student_excluded_from_course | studentId, courseId |
| Teacher signs | on_teacher_sign | teacher, course, signature |
| Teacher created | on_teacher_created | teacherId |
| Teacher edited | on_teacher_edited | teacherId |
| Teacher deleted | on_teacher_deleted | teacherId |
| Teacher restored | on_teacher_unremoved | teacherId |
| Group created | on_group_created | groupId |
| Group edited | on_group_edited | groupId |
| Group deleted | on_group_deleted | groupId |
| Group restored | on_group_unremoved | groupId |
| Course created | on_course_created | courseId |
| Course edited | on_course_edited | courseId |
| Course deleted | on_course_deleted | courseId |
| Course locked | on_course_locked | courseId, ATTENDANCE_LIST_GENERATED |
| Course starts | on_course_start | courseId |
| Course ends | on_course_end | courseId |
| Course unlocked | on_course_unlocked | courseId |
| Training started | on_training_started | trainingId |
| Training ended | on_training_ended | trainingId |
| Training archived | on_training_archived | trainingId |
| Document completed | on_document_completed | documentId, DOCUMENT_URL, DOCUMENT_PROOF_URL |
| Document participant signed | on_document_participant_signed | documentId, participant |
| Document sent | on_document_sent | documentId, recipientId, recipientType, withSignature |
| Document with signature sent | on_document_with_signature_sent | documentId, recipientId, recipientType |
| Document without signature sent | on_document_without_signature_sent | documentId, recipientId, recipientType |
| Document refused | on_document_refused | documentId, recipientId, recipientType, reason |
| Document expired | on_document_expired | documentId |
| Survey answered | on_survey_answer | surveyId, recipientId, recipientType, studentId / professorId / externalId |
| Survey sent | on_survey_sent | surveyId, recipientId, recipientType |
| Scheduled survey sent | on_scheduled_survey_sent | surveyId, courseId, trainingId, recipientIds, recipientCount |
| Absence justified | on_justified_absence | absence |
| Absence justification requested | on_request_justified_absence | absenceRequest |
| Absence report generated | on_abscence_report_generated | studentId, externalId, pdfUrl |
| Email invalid | on_email_invalid | email, invalid_type, invalid_reason |
| Zoom meeting created | on_zoom_meeting_created | COURSE_ID, meeting |
| App parameters changed | on_app_parameters_changed | parameters |
| Daily cron | cron_midnight | (no additional fields) |
Notes
- Course and absence dates are in the school's timezone without offset, event timestamps in UTC โ see Date and Time Format in Webhooks.
appIdis only present on webhooks sent on behalf of a marketplace app โ see Webhook payloads reference.- A delivery can be retried, so the same webhook can be received more than once โ see Auto retry.
- on_zoom_meeting_created uses COURSE_ID (uppercase) โ this is inconsistent with other course webhooks that use courseId.
- on_abscence_report_generated has a typo in the event name (abscence instead of absence) โ this is kept for backward compatibility.
- The meeting object in on_zoom_meeting_created is passed through as-is from Zoom โ the exact fields may vary but always include ID, URL, START, END.
Updated about 1 month ago

