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:

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 here.

We will update and add more events in the upcoming months.

Auto retry

Currently there is no auto-retry scenario.

However, if the webhooks fails, Edusign will send a notification into the dashboard. Moreover, webhooks automatically timeout at 15 seconds.

Date and Time Format in Webhooks

🕒

Important: Date and time values in webhook payloads are expressed in your school's configured timezone, not in UTC.

When Edusign sends webhook payloads, all date and time fields (such as REQUEST_DATE, course start/end times, etc.) are automatically converted to match your school's timezone setting.

Example: If your school is configured with Paris timezone in your Edusign settings, all dates and times in webhook payloads will be in Paris time (CET/CEST), not UTC.

This means you don't need to perform timezone conversions when processing webhook data - the times are already in your school's local timezone for convenience.

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. Your application should:

1. Retrieve the HMAC signature from the x-edusign-hmac header
2. Use your app's Client Secret to generate your own signature
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.

⚠️

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
5. ✅ Implement HMAC verification using your Client Secret
6. ✅ Test your webhook with a sample event