Webhooks

Listen to asynchronous events on the People Index network to keep your systems in sync.

Overview

Webhooks allow your application to receive real-time HTTP notifications when events occur in People Index. This is particularly crucial for ATS and HRMS integrations where you don't want to poll for candidate consent or professional trust scoring completion.

Supported Events

• consent.granted - Fired when a candidate approves a data release request.
• consent.denied - Fired when a candidate explicitly rejects a request.
• credential.issued - Fired when a new verifiable credential is minted to a wallet you manage.
• credential.revoked - Fired when an issuer revokes an active credential.

Security & Verification

All webhook payloads are signed with a cryptographic signature in the X-PeopleIndex-Signature header. You must verify this signature to ensure the webhook genuinely originated from us.

import { webhooks } from '@peopleindex/node';
import express from 'express';

const app = express();

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-peopleindex-signature'];
  
  try {
    const event = webhooks.verifySignature(
      req.body,
      signature,
      process.env.WEBHOOK_SECRET
    );
    
    // Process the event
    if (event.type === 'consent.granted') {
      triggerATSUpdate(event.data.subjectId);
    }
    
    res.json({ received: true });
  } catch (err) {
    res.status(400).send('Webhook Error: Invalid Signature');
  }
});