Skip to main content
Humanos provides a comprehensive webhook system that allows organizations to receive real-time notifications when specific events occur in their processes. All webhook events are delivered to a single configured endpoint, providing a unified interface for handling all event types.

Event Types

Event TypeDescription
credentialA credential (consent, form, signature, mandate) was accepted or rejected
identityAn identity verification (KYC) was completed
otp.failedOTP delivery failed

Base Event Structure

All webhook events share a common base structure:
{
  "eventType": "credential",
  "requestId": "68c42ec3e47c9a7f9241e0ba",
  "internalId": "req_internal_001",
  "issuerDid": "did:via:org-abc123",
  "user": {
    "contact": "+1234567890",
    "did": "did:via:user-xyz789",
    "internalId": "user_98765"
  },
  "decisionDate": "2024-01-15T18:30:00.000Z"
}
FieldTypeRequiredDescription
eventTypestringYesType of event (credential, identity, otp.failed)
requestIdstringYesRequest identifier
internalIdstringNoYour internal identifier for the request
issuerDidstringYesDID of the organization/issuer
userobjectYesObject containing user identity fields
decisionDateDateYesTimestamp when the event occurred

User Object

FieldTypeRequiredDescription
contactstringYesUser’s contact information (phone or email)
didstringYesDID of the user/subject
internalIdstringNoYour internal identifier for the user

Configuration

To configure the webhook system, organization administrators can navigate to Humanos Admin – Webhooks. The following settings are available:
  • Webhook URL is the endpoint where all webhook events will be delivered (e.g., https://your.domain.com/webhook).
  • Webhook Signature Secret is used for validating that the webhooks were sent by Humanos.
  • Webhook Encryption Secret is used for decrypting the payloads, ensuring security on transit.
  • Webhook Encryption Salt is used together with the Webhook Encryption Secret to derive the final encryption key. The salt adds uniqueness and protects against dictionary or pre-computed attacks, ensuring stronger security for each payload.
import crypto from "crypto";

function generateSignature(data, secret, timestamp) {
  const hmac = crypto.createHmac("sha256", secret);
  hmac.update(data ? `${timestamp}.${data}` : timestamp.toString());
  return hmac.digest("hex");
}
const express = require("express");
const crypto = require("crypto");
const app = express();
app.use(express.json());
const SIGNATURE_SECRET = "your-signature-secret";
const ENCRYPTION_SECRET = "your-encryption-secret";
const ENCRYPTION_SALT = "your-encryption-salt";
app.post("/webhook", (req, res) => {
  try {
    const signature = req.headers["x-signature"];
    const timestamp = req.headers["x-timestamp"];
    // 1. Verify signature
    const expected = generateSignature(req.body, SIGNATURE_SECRET, timestamp);
    if (signature !== expected)
      return res.status(401).send("Invalid signature");
    // 2. Decrypt payload
    const { iv, data, tag } = req.body;
    const key = crypto.pbkdf2Sync(
      Buffer.from(ENCRYPTION_SECRET, "base64"),
      ENCRYPTION_SALT,
      10000,
      32,
      "sha256"
    );
    const decipher = crypto.createDecipheriv(
      "aes-256-gcm",
      key,
      Buffer.from(iv, "base64")
    );
    decipher.setAuthTag(Buffer.from(tag, "base64"));
    const decrypted = Buffer.concat([
      decipher.update(Buffer.from(data, "base64")),
      decipher.final(),
    ]).toString("utf8");
    const webhook = JSON.parse(decrypted);
    console.log("Webhook received:", webhook);
    res.sendStatus(200);
  } catch (err) {
    res.status(500).send(err.message);
  }
});
app.listen(5000, () => console.log("Listening on port 5000"));
The provided code snippet implements an express API containing an endpoint to deal with Humanos Webhook notifications. The request should be handled as follows:
  1. Receive the request → Your endpoint will be called with an encrypted payload.
  2. Verify authenticity → Check the x-signature header using your Webhook Signature Secret.
  3. Decrypt the payload → Use the Webhook Encryption Secret and Webhook Encryption Salt to decrypt the message and read the event data.
  4. Process the event → Store it in your system, update statuses, or trigger business logic.
  5. Respond quickly → Always return 200 OK after successful processing. Humanos retries failed deliveries automatically.