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. You can configure several endpoints, and every endpoint receives every event type.

Event Type	Description
credential	A credential such as a form, signature, or mandate was accepted or rejected
identity	An identity verification (KYC) was completed
otp.failed	A one-time code sent by SMS could not be delivered
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-09-01",
  "requestId": "68c42ec3e47c9a7f9241e0ba",
  "internalId": "req_internal_001",
  "issuerDid": "did:web:humanos.tech:org:550e8400-e29b-41d4-a716-446655440000",
  "user": {
    "contact": "[phone]",
    "id": "did:web:humanos.tech:user:73ebefdd-a549-4873-aad9-def80c40c8c8",
    "internalId": "user_98765"
  }
}

eventType · string · required

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

api_version · string · required

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

requestId · string · required

Identifier of the request this event belongs to.

issuerDid · string · required

DID of your organization, the issuer.

internalId · string

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

user · object · required

The subject the event concerns.

Show user

contact · string · required

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

id · string · required

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

internalId · 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

credential · object · required

The credential that was decided.

Show credential

id · string · required

URN of the credential.

resourceType · string · required

DOCUMENT, FORM, JSON, or POLICY.

status · string · required

DRAFT, ACTIVE, or INACTIVE.

name · string

Human-readable name of the credential.

description · string

Free-text description of the credential.

internalId · string

Your own identifier for the credential.

tags · string[]

Free-form labels attached to the credential.

w3cCredential · object · required

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

decisions · object[] · required

Per-grantor decision records for the credential.

decision · object · required

The subject’s decision on the credential.

Show decision

action · string · required

Either accept or reject.

date · string · required

ISO 8601 timestamp of when the decision was made.

identity

decision · object · required

The identity-verification (KYC) outcome.

Show decision

success · boolean · required

Whether verification succeeded.

date · string · required

ISO 8601 timestamp of the decision.

message · string

Human-readable detail, such as a rejection reason.

identity · object

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

Show identity

fullName · string · required

Full name as printed on the document.

birth · string · required

Date of birth, in ISO 8601.

docId · string · required

Document number.

fullDocId · string · required

Extended document number.

countryAlpha3 · string · required

ISO 3166-1 alpha-3 country code.

gender · string | null

Gender as recorded on the document.

nationality · string

Nationality.

placeOfBirth · string

Place of birth.

placeOfIssue · string

Place the document was issued.

documentType · string

Document type, such as PASSPORT or ID_CARD.

issueDate · string

Document issue date.

expiresAt · string

Document expiry date.

addresses · string[]

Addresses on record.

height · number

Height.

weight · number

Weight.

otp.failed

otp · object · required

Details of the failed OTP delivery.

Show otp

resendEndpoint · string · required

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

error · object · required

Show error

code · string · required

Machine-readable error code.

message · string · required

Human-readable error detail.

test

message · string · required

A static confirmation message, sent when you trigger a test webhook from the dashboard.

Versioning

By default, each delivery is formatted for the API version its request was created under: the API-Version header sent on POST /request, or else the version pinned to the API key. You can optionally pin an endpoint to a fixed version in the Humanos Dashboard; a pinned endpoint receives every event in that version’s format.

Every webhook payload includes an api_version field so you always know which format it uses.

For more details on how versioning works across the API and webhooks, see API Versioning.

Configuration

To configure webhooks, organization administrators can open Webhooks in the Humanos Dashboard. Each endpoint has the following settings:

• Endpoint URL is an HTTPS endpoint where webhook events are delivered, for example https://your.domain.com/webhook. Each endpoint gets its own secrets and salt, shown once when you create or rotate them, plus optional Basic Auth and an optional API version pin.
• 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 in 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 app 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 → Return a 2xx status, such as 200 OK, within 30 seconds. Humanos retries failed deliveries automatically, up to 9 attempts over about 17 hours; 401, 403 and 410 responses are treated as permanent and not retried.