Webhooks

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 Type	Description
`credential`	A credential such as consent, form, signature, or mandate was accepted or rejected
`identity`	An identity verification (KYC) was completed
`otp.failed`	OTP delivery failed
`test`	Delivered when you send a test webhook from the dashboard

Event Payload

All webhook events share a common base structure:

{
  "eventType": "credential",
  "api_version": "2026-07-06",
  "requestId": "68c42ec3e47c9a7f9241e0ba",
  "internalId": "req_internal_001",
  "issuerDid": "did:web:humanos.tech:org:550e8400-e29b-41d4-a716-446655440000",
  "user": {
    "contact": "+351912345678",
    "id": "did:web:humanos.tech:user:73ebefdd-a549-4873-aad9-def80c40c8c8",
    "internalId": "user_98765"
  }
}

string

required

The event type: credential, identity, otp.failed, or test.

string

required

API version the payload is formatted for, given as YYYY-MM-DD.

string

required

Identifier of the request this event belongs to.

string

required

DID of your organization, the issuer.

string

Your internal identifier for the request, if you set one.

object

required

The subject the event concerns.

Show user

string

required

The subject’s contact, an email or phone number.

string

required

Subject identifier, a DID such as did:web:….

string

Your internal identifier for the user, if you set one.

Then, keyed by eventType, each event adds its own fields. Pick the event you are handling:

credential
identity
otp.failed
test

object

required

The credential that was decided.

Show credential

string

required

URN of the credential.

string

required

DOCUMENT, CONSENT, FORM, JSON, or POLICY.

string

required

DRAFT, ACTIVE, REJECTED, CANCELED, REVOKED, or EXPIRED.

string

Human-readable name of the credential.

string

Free-text description of the credential.

string

Your own identifier for the credential.

string[]

Free-form labels attached to the credential.

object

required

The signed W3C Verifiable Credential, in the VIA protocol, is the full credential document. See its schema on any credential endpoint in the API reference.

object[]

required

Per-grantor decision records for the credential.

object

required

The subject’s decision on the request.

Show decision

string

required

Either accept or reject.

string

required

ISO 8601 timestamp of when the decision was made.

object

required

The identity-verification (KYC) outcome.

Show decision

boolean

required

Whether verification succeeded.

string

required

ISO 8601 timestamp of the decision.

string

Human-readable detail, such as a rejection reason.

object

Data extracted from the verified document. Present on success; omitted when verification did not complete.

Show identity

string

required

Full name as printed on the document.

string

required

Date of birth, in ISO 8601.

string

required

Document number.

string

required

Extended document number.

string

required

ISO 3166-1 alpha-3 country code.

string | null

Gender as recorded on the document.

string

Nationality.

string

Place of birth.

string

Place the document was issued.

string

Document type, such as passport or id_card.

string

Document issue date.

string

Document expiry date.

string[]

Addresses on record.

number

Height.

number

Weight.

object

required

Details of the failed OTP delivery.

Show otp

string

required

PATCH this URL exactly as delivered to issue a fresh code. Doing so invalidates the old one.

object

required

Show error

string

required

Machine-readable error code.

string

required

Human-readable error detail.

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, for example 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: HMAC over the raw JSON body string (the {iv,data,tag} envelope)
    const expected = generateSignature(
      JSON.stringify(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:

Receive the request → Your endpoint will be called with an encrypted payload.
Verify authenticity → Check the x-signature header using your Webhook Signature Secret.
Decrypt the payload → Use the Webhook Encryption Secret and Webhook Encryption Salt to decrypt the message and read the event data.
Process the event → Store it in your system, update statuses, or trigger business logic.
Respond quickly → Always return 200 OK after successful processing. Humanos retries failed deliveries automatically.

Getting started

Guides

Event Payload

Versioning

Configuration

​Event Payload

​Versioning

​Configuration

Event Payload

Versioning

Configuration