Skip to main content

Documentation Index

Fetch the complete documentation index at: https://humanos.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Versioning

Webhook payloads are versioned independently from the API. Each organization has its own webhook version, which determines the format of the payloads you receive. You can manage your webhook version in the Humanos Dashboard. Every webhook payload includes an api_version field so you always know which format it uses. Your webhook version is automatically set on the first delivery and stays pinned until you explicitly change it. For more details on how versioning works across the API and webhooks, see API Versioning.

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