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:

FeatureAPI KeysClient Secret
PurposeGeneral API authenticationWebhook HMAC signature verification
QuantityUp to 5 per school1 per app
UsageAuthorization: Bearer <API_KEY>HMAC signature validation
ScopeAll API endpointsWebhook security only

Creating an Edusign App

To obtain a Client ID and Client Secret, you need to create an Edusign App:

  1. Go to your school dashboard: Private Apps
  2. Create a new app (can remain private or be published publicly after validation)
  3. 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 POST requests with a JSON body, and time out after 15 seconds.
  • Your endpoint must answer with a 2xx status 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.
FieldEventsTimezoneFormatExample
course.START, course.ENDon_student_sign, on_teacher_signSchool's timezoneYYYY-MM-DD HH:mm:ss2026-03-26 09:00:00
absence.START, absence.ENDon_justified_absenceSchool's timezoneYYYY/MM/DD HH:mm:ss2026/03/26 09:00:00
absence.REQUEST_DATEon_justified_absenceSchool's timezoneYYYY-MM-DD HH:mm:ss2026-03-25 14:00:00
signature.timestampon_student_sign, on_teacher_signUTCISO 86012026-03-26T08:15:00+00:00
submittedAton_survey_answerUTCISO 8601, with milliseconds2026-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:

  1. Retrieve the HMAC signature from the x-edusign-hmac header
  2. Compute the HMAC-SHA256 of the raw request body โ€” as received, before any JSON parsing โ€” with your app's Client Secret
  3. 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 library

You 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:

  1. โœ… Create an Edusign App
  2. โœ… Note your Client Secret (for HMAC verification)
  3. โœ… Note your API Key (for making API requests)
  4. โœ… Configure your webhook endpoint URL in Edusign settings or through the API
  5. โœ… Implement HMAC verification using your Client Secret
  6. โœ… Make your processing idempotent โ€” a delivery can be retried (see Auto retry)
  7. โœ… 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.

FieldTypeDescription
typestringThe webhook event type (see the sections below)
appIdstringThe 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:

HeaderDescription
Content-Typeapplication/json
User-AgentEdusign-Webhook/1.0
x-edusign-webhook-typeThe event type (e.g. on_student_sign)
x-edusign-school-idThe ID of the school the event belongs to
x-edusign-langLanguage code of the school (default: fr)
x-edusign-app-idThe App Marketplace ID โ€” app webhooks only, absent for school webhooks
x-edusign-hmacHMAC-SHA256 signature of the body โ€” app webhooks only, absent for school webhooks
x-edusign-client-idApp 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
    }
  ]
}
FieldDescription
surveyIdID of the survey
recipientIdID of the respondent โ€” the string anonymous on an anonymous survey
recipientTypestudent, professor or external
studentId / professorId / externalIdID of the respondent. Only one of the three is sent, the one matching recipientType โ€” anonymous on an anonymous survey
surveyTypesurvey or quiz
isAnonymoustrue for an anonymous survey
submittedAtWhen the answer was submitted, in UTC (ISO 8601)
nbQuestionsNumber of questions in the survey โ€” one item per question in responses
nbCorrectAnswersNumber of correct answers. Optional: only sent when surveyType is quiz
responsesOne 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

EventType stringKey payload fields
Student signson_student_signstudent, course, signature
Student createdon_student_createdstudentId
Student editedon_student_editedstudentId
Student deletedon_student_deletedstudentId
Student restoredon_student_unremovedstudentId
Student archivedon_student_archivedstudentId
Student unarchivedon_student_unarchivedstudentId
Student excluded from courseon_student_excluded_from_coursestudentId, courseId
Teacher signson_teacher_signteacher, course, signature
Teacher createdon_teacher_createdteacherId
Teacher editedon_teacher_editedteacherId
Teacher deletedon_teacher_deletedteacherId
Teacher restoredon_teacher_unremovedteacherId
Group createdon_group_createdgroupId
Group editedon_group_editedgroupId
Group deletedon_group_deletedgroupId
Group restoredon_group_unremovedgroupId
Course createdon_course_createdcourseId
Course editedon_course_editedcourseId
Course deletedon_course_deletedcourseId
Course lockedon_course_lockedcourseId, ATTENDANCE_LIST_GENERATED
Course startson_course_startcourseId
Course endson_course_endcourseId
Course unlockedon_course_unlockedcourseId
Training startedon_training_startedtrainingId
Training endedon_training_endedtrainingId
Training archivedon_training_archivedtrainingId
Document completedon_document_completeddocumentId, DOCUMENT_URL, DOCUMENT_PROOF_URL
Document participant signedon_document_participant_signeddocumentId, participant
Document senton_document_sentdocumentId, recipientId, recipientType, withSignature
Document with signature senton_document_with_signature_sentdocumentId, recipientId, recipientType
Document without signature senton_document_without_signature_sentdocumentId, recipientId, recipientType
Document refusedon_document_refuseddocumentId, recipientId, recipientType, reason
Document expiredon_document_expireddocumentId
Survey answeredon_survey_answersurveyId, recipientId, recipientType, studentId / professorId / externalId
Survey senton_survey_sentsurveyId, recipientId, recipientType
Scheduled survey senton_scheduled_survey_sentsurveyId, courseId, trainingId, recipientIds, recipientCount
Absence justifiedon_justified_absenceabsence
Absence justification requestedon_request_justified_absenceabsenceRequest
Absence report generatedon_abscence_report_generatedstudentId, externalId, pdfUrl
Email invalidon_email_invalidemail, invalid_type, invalid_reason
Zoom meeting createdon_zoom_meeting_createdCOURSE_ID, meeting
App parameters changedon_app_parameters_changedparameters
Daily croncron_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.
  • appId is 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.

Did this page help you?