Webhooks

Receive real-time notifications about request events and user actions

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 Type	Description
credential	A credential (consent, form, signature, mandate) was accepted or rejected
identity	An identity verification (KYC) was completed
otp.failed	OTP 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": "[phone]",
    "did": "did:via:user-xyz789",
    "internalId": "user_98765"
  },
  "decisionDate": "2024-01-15T18:30:00.000Z"
}

Field	Type	Required	Description
eventType	string	Yes	Type of event (credential, identity, otp.failed)
requestId	string	Yes	Request identifier
internalId	string	No	Your internal identifier for the request
issuerDid	string	Yes	DID of the organization/issuer
user	object	Yes	Object containing user identity fields
decisionDate	Date	Yes	Timestamp when the event occurred

User Object

Field	Type	Required	Description
contact	string	Yes	User’s contact information (phone or email)
did	string	Yes	DID of the user/subject
internalId	string	No	Your 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.