Webhook

Webhook Documentation

Objective

Webhooks allow your system to receive real-time notifications as a verification operation progresses:

operation start,
evidence captures (document, selfie, NFC),
biometric evaluations,
final result.

With this, you can update business states, trigger rules, and show traceability to the end user without continuously polling.

How delivery works

You configure an HTTPS reception URL in your integration.
The system sends events via POST with a JSON payload.
Only the events you have subscribed to in your configuration are sent.
Each message includes a signature to validate authenticity.

Recommendation for your Endpoint:

respond quickly with 2xx when the message is accepted,
process asynchronously when possible,
handle idempotency using id of the event.

Security and authenticity

Each webhook includes:

header Content-Type: application/json,
custom security headers (if you defined them),
field signature within the payload.

The signature is calculated with HMAC SHA-256 over the event content and a shared integration key. You must validate this signature before considering the message trustworthy.

General webhook structure

All events follow the same base structure:

{
	"specversion": "1.0",
	"id": "uuid-del-evento",
	"type": "com.idv_suite.api.workflows.algo.v1",
	"source": "/operations/{operationId}",
	"time": "2026-03-06T12:00:00.000Z",
	"data": {},
	"signature": "firma-hmac-base64"
}

Field meanings:

id: unique message identifier (use to avoid duplicates).
type: event type (defines how to interpret data).
source: originating operation of the event.
time: UTC emission date/time.
data: business content of the event.
signature: message signature.

TypeScript Base

All events share this base envelope:

type WebhookSource = `/operations/${string}`;

type WebhookEnvelope<TType extends string, TData> = {
	specversion: '1.0';
	id: string;
	type: TType;
	source: WebhookSource;
	time: string;
	data: TData;
	signature: string;
};

Modeling notes:

specversion today is always "1.0".
id, time and signature they do not have a closed catalog.
source always follows the pattern /operations/{operationId}.
In each event, only the values explicitly set by the current implementation are closed as an enum.
When an external provider or an internal stage does not define a closed catalog, the field should be left as string, Record<string, unknown> or an equivalent open structure.

Events currently available

1) Operation started

Type: com.idv_suite.api.workflows.operation_started.v1
When sent: when creating/starting an operation.
What it is for: open operation tracking and correlate it with your systems.

TypeScript typing:

type OperationStartedWebhook = WebhookEnvelope<
	'com.idv_suite.api.workflows.operation_started.v1',
	{
		sessionId: string;
		authenticationId?: string;
		customerId: string;
		source: string;
		document?: {
			type?: string;
			number?: string;
			issuer?: string;
			gender?: string;
			code?: string;
			name?: string;
			surname?: string;
		};
	}
>;

Example:

{
	"specversion": "1.0",
	"id": "4f65587f-2c4f-4ea2-b7ff-8fbf7d6fe8e8",
	"type": "com.idv_suite.api.workflows.operation_started.v1",
	"source": "/operations/5f2d2e8d-0f0f-4cae-8fc1-55756b6d06f3",
	"time": "2026-03-06T12:00:00.000Z",
	"data": {
		"customerId": "user-123",
		"sessionId": "sess-789",
		"source": "sdk.mobile"
	},
	"signature": "firma-hmac-base64"
}

Type: com.idv_suite.api.workflows.terms_consent.v1
When sent: when accepting or rejecting terms.
What it is for: legal traceability and flow continuity rules.

TypeScript typing:

type TermsConsentWebhook = WebhookEnvelope<
	'com.idv_suite.api.workflows.terms_consent.v1',
	{
		stepId: string;
		success: boolean;
		timestamp: string;
		accepted: 'accepted' | 'rejected';
	}
>;

Example:

{
	"specversion": "1.0",
	"id": "18a26cf2-4556-4f69-9be5-e0b677f4de82",
	"type": "com.idv_suite.api.workflows.terms_consent.v1",
	"source": "/operations/5f2d2e8d-0f0f-4cae-8fc1-55756b6d06f3",
	"time": "2026-03-06T12:00:15.000Z",
	"data": {
		"stepId": "1d80cdd1-9dfb-4ef3-b0aa-530f2db60a02",
		"success": true,
		"timestamp": "2026-03-06T12:00:14.000Z",
		"accepted": "accepted"
	},
	"signature": "firma-hmac-base64"
}

3) Captured document (ID/OCR)

Type: com.idv_suite.api.workflows.id_captured.v1
When sent: when document capture and data extraction are completed.
What it is for: populate document data and validate consistency.

TypeScript typing:

type IdCapturedWebhook = WebhookEnvelope<
	'com.idv_suite.api.workflows.id_captured.v1',
	{
		stepId: string;
		success: boolean;
		data: Record<string, unknown>;
		summary: Record<string, unknown>;
		assets?: string[];
	}
>;

Notes:

data and summary do not have a closed schema in the current implementation.
assets contains asset IDs associated with the event.

Example:

{
	"specversion": "1.0",
	"id": "426133f2-50ea-4f4c-8fe8-5435286ea737",
	"type": "com.idv_suite.api.workflows.id_captured.v1",
	"source": "/operations/5f2d2e8d-0f0f-4cae-8fc1-55756b6d06f3",
	"time": "2026-03-06T12:01:50.000Z",
	"data": {
		"stepId": "7f4af246-d48c-4ce6-b3b1-bdf65ba7c9dd",
		"success": true,
		"data": {
			"documentNumber": "X1234567"
		},
		"summary": {
			"name": "JUAN",
			"surname": "MARTINEZ"
		},
		"assets": ["asset-portrait-id", "asset-signature-id"]
	},
	"signature": "firma-hmac-base64"
}

4) Selfie captured

Type: com.idv_suite.api.workflows.selfie_captured.v1
When sent: when face capture is completed.
What it is for: mark progress in the biometric stage.

TypeScript typing:

type SelfieCapturedWebhook = WebhookEnvelope<
	'com.idv_suite.api.workflows.selfie_captured.v1',
	{
		stepId: string;
	}
>;

Example:

{
	"specversion": "1.0",
	"id": "f0d3da62-0711-4b50-93f8-5034b4d4a4bb",
	"type": "com.idv_suite.api.workflows.selfie_captured.v1",
	"source": "/operations/5f2d2e8d-0f0f-4cae-8fc1-55756b6d06f3",
	"time": "2026-03-06T12:01:02.000Z",
	"data": {
		"stepId": "ab4b360f-1f6b-4ca4-ae44-8676f3705747"
	},
	"signature": "firma-hmac-base64"
}

5) NFC captured

Type: com.idv_suite.api.workflows.nfc_captured.v1
When sent: when NFC reading of the document occurs.
What it is for: enrich and cross-check document information.

TypeScript typing:

type NfcCapturedWebhook = WebhookEnvelope<
	'com.idv_suite.api.workflows.nfc_captured.v1',
	{
		stepId: string;
		success: boolean;
		data: Record<string, unknown>;
		summary: Record<string, unknown>;
		assets?: string[];
	}
>;

Notes:

Same as in id_captured, data and summary they remain open.

Example:

{
	"specversion": "1.0",
	"id": "cb08900a-8ef2-4f61-95f1-0e39f7686cef",
	"type": "com.idv_suite.api.workflows.nfc_captured.v1",
	"source": "/operations/5f2d2e8d-0f0f-4cae-8fc1-55756b6d06f3",
	"time": "2026-03-06T12:01:30.000Z",
	"data": {
		"stepId": "17761cae-0150-43f7-a5b2-a15e7a59f659",
		"success": true,
		"data": {
			"documentNumber": "X1234567"
		},
		"summary": {
			"name": "JUAN",
			"surname": "MARTINEZ"
		}
	},
	"signature": "firma-hmac-base64"
}

6) Passive Liveness evaluated

Type: com.idv_suite.api.workflows.passive_liveness_evaluated.v1
When sent: after evaluating the passive liveness check.
What it is for: detect potential impersonation attempts.

TypeScript typing:

type PassiveLivenessEvaluatedWebhook = WebhookEnvelope<
	'com.idv_suite.api.workflows.passive_liveness_evaluated.v1',
	{
		stepId: string;
		success: boolean;
		diagnostic: string;
		assets?: string[];
	}
>;

Notes:

diagnostic does not have a closed enum in code; the known example is "Live".

Example:

{
	"specversion": "1.0",
	"id": "1029c9ed-8945-46e6-9908-9a76ecf402f4",
	"type": "com.idv_suite.api.workflows.passive_liveness_evaluated.v1",
	"source": "/operations/5f2d2e8d-0f0f-4cae-8fc1-55756b6d06f3",
	"time": "2026-03-06T12:02:11.000Z",
	"data": {
		"stepId": "95b3f1f9-cf8f-469c-b698-414b3a9656e6",
		"success": true,
		"diagnostic": "Live",
		"assets": ["asset-selfie-id"]
	},
	"signature": "firma-hmac-base64"
}

7) Injection detection

Type: com.idv_suite.api.workflows.injection_attack_detected.v1
When sent: after evaluating injection/synthetic risk.
What it is for: strengthen real-time anti-fraud controls.

TypeScript typing:

type InjectionAttackDetectedWebhook = WebhookEnvelope<
	'com.idv_suite.api.workflows.injection_attack_detected.v1',
	{
		stepId: string;
		success: boolean;
		score: number;
		probability: number;
		status: 'REAL' | 'SPOOF';
		assets?: string[];
	}
>;

Example:

{
	"specversion": "1.0",
	"id": "0203b7e9-5ed4-4444-af6d-46cf15f8fc76",
	"type": "com.idv_suite.api.workflows.injection_attack_detected.v1",
	"source": "/operations/5f2d2e8d-0f0f-4cae-8fc1-55756b6d06f3",
	"time": "2026-03-06T12:02:30.000Z",
	"data": {
		"stepId": "abf8f66f-0b8d-4fce-a593-eb68d51c210f",
		"success": true,
		"score": 0.12,
		"probability": 0.06,
		"status": "REAL",
		"assets": ["asset-selfie-id"]
	},
	"signature": "firma-hmac-base64"
}

8) Facial Matching evaluated

Type: com.idv_suite.api.workflows.facial_authentication_evaluated.v1
When sent: when comparing the document face vs. the selfie.
What it is for: validate biometric correspondence.

TypeScript typing:

type FacialAuthenticationEvaluatedWebhook = WebhookEnvelope<
	'com.idv_suite.api.workflows.facial_authentication_evaluated.v1',
	{
		stepId: string;
		success: boolean;
		authStatus: string;
		similarity: number;
		assets?: string[];
	}
>;

Notes:

authStatus does not have a closed enum in code. The known example is "Positive".

Example:

{
	"specversion": "1.0",
	"id": "0087cf6a-77f9-42f7-8f78-8ae94f32bd9a",
	"type": "com.idv_suite.api.workflows.facial_authentication_evaluated.v1",
	"source": "/operations/5f2d2e8d-0f0f-4cae-8fc1-55756b6d06f3",
	"time": "2026-03-06T12:02:49.000Z",
	"data": {
		"stepId": "6fe21ca0-2914-49ac-b87c-d3c665304be4",
		"success": true,
		"authStatus": "Positive",
		"similarity": 0.93,
		"assets": ["asset-id-portrait", "asset-selfie"]
	},
	"signature": "firma-hmac-base64"
}

9) Facial enrollment

Type: com.idv_suite.api.workflows.facial_enrollment.v1
When sent: when registering a biometric identity.
What it is for: enable future 1:1 authentications.

TypeScript typing:

type FacialEnrollmentWebhook = WebhookEnvelope<
	'com.idv_suite.api.workflows.facial_enrollment.v1',
	{
		stepId: string;
		success: boolean;
		authenticationId: string;
		context: 'AUTHENTICATION_ID';
		assetId: string;
	}
>;

Example:

{
	"specversion": "1.0",
	"id": "3f2f8df8-424a-4489-95eb-105f7f3e5efb",
	"type": "com.idv_suite.api.workflows.facial_enrollment.v1",
	"source": "/operations/5f2d2e8d-0f0f-4cae-8fc1-55756b6d06f3",
	"time": "2026-03-06T12:03:11.000Z",
	"data": {
		"stepId": "9076af18-3de1-4f03-b0f9-ad7deef5d01d",
		"success": true,
		"authenticationId": "auth-123",
		"context": "AUTHENTICATION_ID",
		"assetId": "asset-selfie-id"
	},
	"signature": "firma-hmac-base64"
}

10) 1:1 facial verification

Type: com.idv_suite.api.workflows.facial_verification.v1
When sent: when validating identity against a previous enrollment.
What it is for: authentication or identity confirmation.

TypeScript typing:

type FacialVerificationWebhook = WebhookEnvelope<
	'com.idv_suite.api.workflows.facial_verification.v1',
	{
		stepId: string;
		success: boolean;
		authenticationId: string;
		authStatus: string;
		similarity: number;
		assets: string;
	}
>;

Notes:

authStatus remains open; the known example is "Positive".
assets in this event it is emitted as string simple, not as string[].

Example:

{
	"specversion": "1.0",
	"id": "865fb4e2-65cb-48d9-96a8-157ec95ecef6",
	"type": "com.idv_suite.api.workflows.facial_verification.v1",
	"source": "/operations/5f2d2e8d-0f0f-4cae-8fc1-55756b6d06f3",
	"time": "2026-03-06T12:03:33.000Z",
	"data": {
		"stepId": "7242e76b-3271-4f1b-b702-27042512ec66",
		"success": true,
		"authenticationId": "auth-123",
		"authStatus": "Positive",
		"similarity": 0.95,
		"assets": "asset-selfie-id"
	},
	"signature": "firma-hmac-base64"
}

11) Document Matching evaluated

Type: com.idv_suite.api.workflows.document_matching_evaluated.v1
When sent: when comparing two document sources within the flow.
What it is for: measure consistency between documents or between captures of the same holder.

TypeScript typing:

type DocumentMatchingEvaluatedWebhook = WebhookEnvelope<
	'com.idv_suite.api.workflows.document_matching_evaluated.v1',
	{
		stepId: string;
		score: number;
		status: 'MATCHED' | 'NOT_MATCHED' | 'WEAK_MATCHED' | 'WEAK_NOT_MATCHED';
		fields: Record<
			string,
			{
				source?: string;
				target?: string;
				similarity: number;
				weight: number;
			}
		>;
	}
>;

Example:

{
	"specversion": "1.0",
	"id": "8b3bd547-4fb7-47f0-962d-b7f7d77dbb7d",
	"type": "com.idv_suite.api.workflows.document_matching_evaluated.v1",
	"source": "/operations/5f2d2e8d-0f0f-4cae-8fc1-55756b6d06f3",
	"time": "2026-03-06T12:03:55.000Z",
	"data": {
		"stepId": "d537af32-42c1-44b4-aea5-2a8db31dff2f",
		"score": 0.94,
		"status": "MATCHED",
		"fields": {
			"documentNumber": {
				"source": "X1234567",
				"target": "X1234567",
				"similarity": 1,
				"weight": 1
			}
		}
	},
	"signature": "firma-hmac-base64"
}

12) Operation finished

Type: com.idv_suite.api.workflows.operation_finished.v1
When sent: at operation closure (success, rejection, expiration, or error).
What it is for: define the final decision and close the business process.

TypeScript typing:

type OperationFinishedWebhook = WebhookEnvelope<
	'com.idv_suite.api.workflows.operation_finished.v1',
	{
		status: 'SUCCEEDED' | 'DENIED' | 'ERROR' | 'CANCELLED' | 'BLACKLISTED' | 'EXPIRED';
		reason?: string;
		content: Partial<{
			'passive-liveness': Array<{
				id: string;
				data: {
					success: boolean;
					diagnostic: string;
					assets?: string[];
				};
			}>;
			'injection-attack': Array<{
				id: string;
				data: {
					success: boolean;
					score: number;
					probability: number;
					status: 'REAL' | 'SPOOF';
					assets?: string[];
				};
			}>;
			'face-matching': Array<{
				id: string;
				data: {
					success: boolean;
					authStatus: string;
					similarity: number;
					assets?: string[];
				};
			}>;
			'id-extracted': Array<{
				id: string;
				data: {
					success: boolean;
					data: Record<string, unknown>;
					summary: Record<string, unknown>;
					assets?: string[];
				};
			}>;
			'facial-enrollment': Array<{
				id: string;
				data: {
					success: boolean;
					authenticationId: string;
					context: 'AUTHENTICATION_ID';
					assetId: string;
				};
			}>;
			'facial-verification': Array<{
				id: string;
				data: {
					success: boolean;
					authenticationId: string;
					authStatus: string;
					similarity: number;
					context: 'AUTHENTICATION_ID';
					assets: string;
				};
			}>;
			'document-matching': Array<{
				id: string;
				data: {
					success: boolean;
					score: number;
					status: 'MATCHED' | 'NOT_MATCHED' | 'WEAK_MATCHED' | 'WEAK_NOT_MATCHED';
					fields: Record<string, { source?: string; target?: string; similarity: number; weight: number }>;
				};
			}>;
			'anti-fraud-check': Array<{
				id: string;
				data: {
					success: boolean;
					type: string;
					status: string;
					reason?: string;
					assetId?: string;
					assetHash?: string;
					documentNumber?: string;
					documentType?: string;
					documentCountry?: string;
					deviceId?: string;
					assets?: string[];
				};
			}>;
			'civil-validation': Array<{
				id: string;
				data: {
					serviceResultCode?: number;
					serviceTime?: string;
					serviceResultLog?: string;
					serviceTransactionId?: string;
					serviceFacialAuthenticationResult?: number;
					serviceFacialSimilarityResult?: number;
					civilServiceCountry?: string;
					civilServiceNumber?: string;
					civilServiceData?: Record<string, unknown>;
				};
			}>;
			'document-validation': Array<{
				id: string;
				data: {
					id: string;
					attemptId?: string;
					acceptanceTime?: string;
					decisionTime?: string;
					code?: number;
					vendorData?: string;
					endUserId?: string;
					status?: string;
					reason?: string;
					reasonCode?: number;
					riskScore: number;
					person?: Partial<{
						gender: string;
						idNumber: string;
						lastName: string;
						firstName: string;
						citizenship: string;
						dateOfBirth: string;
						nationality: string;
						yearOfBirth: string;
						placeOfBirth: string;
						pepSanctionMatch: boolean | string;
					}>;
					document?: Partial<{
						type: string;
						state: string;
						number: string;
						country: string;
						validFrom: string;
						validUntil: string;
					}>;
				};
			}>;
		}>;
	}
>;

Example:

{
	"specversion": "1.0",
	"id": "63f5f4f7-a4f7-43f7-aa27-f1f49f6fe131",
	"type": "com.idv_suite.api.workflows.operation_finished.v1",
	"source": "/operations/5f2d2e8d-0f0f-4cae-8fc1-55756b6d06f3",
	"time": "2026-03-06T12:04:10.000Z",
	"data": {
		"status": "DENIED",
		"reason": "FACE_MATCHING_FAILED",
		"content": {
			"face-matching": [
				{
					"id": "6fe21ca0-2914-49ac-b87c-d3c665304be4",
					"data": { "success": true, "authStatus": "Positive", "similarity": 0.93 }
				}
			]
		}
	},
	"signature": "firma-hmac-base64"
}

PreviousVideo recording NextProduct Manual

Last updated 4 months ago

Webhook Documentation

Objective

How delivery works

Security and authenticity

General webhook structure

TypeScript Base

Events currently available

1) Operation started

2) Terms consent

3) Captured document (ID/OCR)

4) Selfie captured

5) NFC captured

6) Passive Liveness evaluated

7) Injection detection

8) Facial Matching evaluated

9) Facial enrollment

10) 1:1 facial verification

11) Document Matching evaluated

12) Operation finished