Website
Env:
Home/API Docs/Webhooks & Events

Webhooks & Realtime Events

Receive automated HTTP push notifications when sessions complete, participants join, or documents are signed.

Instant Event Delivery

Eliminates constant polling. Your backend is instantly updated the moment an action occurs in the notary room.

HMAC SHA-256 Signatures

Every delivery includes an X-Eznotary-Signature header computed with your webhook saltKey.

Automatic Retry Policy

If your server does not respond with 2xx within 5s, EZNotary automatically retries up to 3 times with exponential backoff.

Verifying Webhook Signatures

Compute HMAC SHA-256 of the JSON request body using your webhook saltKey and compare with X-Eznotary-Signature.

Webhook Verification (Node.js)
import crypto from 'crypto';
import express from 'express';

const app = express();
// Ensure you capture the raw body string for HMAC calculation
app.use(express.json());

app.post('/webhooks/eznotary', (req, res) => {
  const signature = req.headers['x-eznotary-signature'];
  const event = req.headers['x-eznotary-event'];
  const saltKey = process.env.EZNOTARY_WEBHOOK_SALT_KEY;

  // Calculate HMAC SHA-256
  const expectedSignature = crypto
    .createHmac('sha256', saltKey)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expectedSignature) {
    console.error('Invalid signature! Rejecting payload.');
    return res.status(401).send('Invalid signature');
  }

  console.log(`Received valid event: ${event}`, req.body);
  
  // Handle event
  switch (event) {
    case 'session.completed':
      // Download notarized document or update DB
      break;
    default:
      break;
  }

  // Always return 200 OK within 5 seconds
  res.status(200).json({ received: true });
});

Supported Webhook Events

Click an event to preview its payload schema:

session.completedPayload Schema

Triggered when a notarization session is legally finalized and sealed by the notary.

Payload: session.completed
{
  "sessionId": "SES-2611-8934",
  "externalReference": "APP-LN-2026-88912",
  "status": "completed"
}

Webhook Management Endpoints

Programmatically register and list webhook listeners

POST/webhooks
API Key Required

Register Webhook Endpoint

Subscribes your backend to specific events or all events using `*`. EZNotary generates a unique saltKey used to compute HMAC SHA-256 signatures for payload verification.

URL:https://eznotary.in/api/v1/webhooks
Request Parameters

Headers

HeaderTypeRequiredDescription
x-api-keystringRequiredTenant API Key generated from the EZNotary B2B Developer Portal.
x-api-secretstringRequiredTenant API Secret key paired with your API key.

Request Body Parameters

Format: application/json
FieldTypeRequiredDescription
url
stringRequired
Your HTTPS webhook callback receiver endpoint.
Example: https://api.yourcompany.com/webhooks/eznotary
events
array of stringsRequired
Array of event names to subscribe to, or `["*"]` for all events.
Example: ["session.completed", "participant.joined", "kyc.verified"]
Allowed:*session.createdsession.rescheduledsession.cancelledsession.completedparticipant.createdparticipant.joinedkyc.verifiedesign.signedesign.failed
cURL — Register Webhook Endpoint
curl -X POST "https://eznotary.in/api/v1/webhooks" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://api.yourcompany.com/webhooks/eznotary",
  "events": [
    "session.completed",
    "participant.joined",
    "kyc.verified"
  ]
}'
GET/webhooks
API Key Required

List Registered Webhooks

Returns all configured webhook URLs, active subscriptions, and salt keys for your tenant account.

URL:https://eznotary.in/api/v1/webhooks
Request Parameters

Headers

HeaderTypeRequiredDescription
x-api-keystringRequiredTenant API Key generated from the EZNotary B2B Developer Portal.
x-api-secretstringRequiredTenant API Secret key paired with your API key.
cURL — List Registered Webhooks
curl -X GET "https://eznotary.in/api/v1/webhooks" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET"