Skip to main content

Webhook Events

Complete reference of all webhook events you can subscribe to in TrustGate.

Applicant Events​

applicant.created​

Triggered when a new applicant is created.

{
  "id": "evt_123456",
  "type": "applicant.created",
  "created_at": "2025-01-20T14:00:00Z",
  "data": {
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "created_at": "2025-01-20T14:00:00Z"
  }
}

applicant.updated​

Triggered when applicant information is updated.

{
  "id": "evt_123457",
  "type": "applicant.updated",
  "created_at": "2025-01-20T14:05:00Z",
  "data": {
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "changes": {
      "address": {
        "previous": null,
        "current": {
          "line1": "123 Main St",
          "city": "San Francisco"
        }
      }
    }
  }
}

applicant.verified​

Triggered when an applicant passes all verification checks.

{
  "id": "evt_123458",
  "type": "applicant.verified",
  "created_at": "2025-01-20T14:30:00Z",
  "data": {
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "verification_level": "standard",
    "checks_completed": ["document", "biometric", "screening"],
    "risk_score": 25,
    "verified_at": "2025-01-20T14:30:00Z"
  }
}

applicant.rejected​

Triggered when an applicant is rejected.

{
  "id": "evt_123459",
  "type": "applicant.rejected",
  "created_at": "2025-01-20T14:30:00Z",
  "data": {
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "rejection_reason": "sanctions_match",
    "rejection_details": "Confirmed match on OFAC SDN list",
    "rejected_at": "2025-01-20T14:30:00Z"
  }
}

applicant.pending_review​

Triggered when an applicant requires manual review.

{
  "id": "evt_123460",
  "type": "applicant.pending_review",
  "created_at": "2025-01-20T14:30:00Z",
  "data": {
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "review_reasons": ["screening_hit", "high_risk_country"],
    "case_id": "case_789012"
  }
}

Document Events​

document.uploaded​

Triggered when a document is uploaded.

{
  "id": "evt_123461",
  "type": "document.uploaded",
  "created_at": "2025-01-20T14:10:00Z",
  "data": {
    "document_id": "doc_456789",
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "document_type": "passport",
    "side": "front"
  }
}

document.verified​

Triggered when document verification completes.

{
  "id": "evt_123462",
  "type": "document.verified",
  "created_at": "2025-01-20T14:15:00Z",
  "data": {
    "document_id": "doc_456789",
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "document_type": "passport",
    "verification_status": "verified",
    "extracted_data": {
      "full_name": "JOHN DOE",
      "date_of_birth": "1985-03-15",
      "document_number": "123456789",
      "expiry_date": "2030-06-15",
      "issuing_country": "USA"
    }
  }
}

document.rejected​

Triggered when a document is rejected.

{
  "id": "evt_123463",
  "type": "document.rejected",
  "created_at": "2025-01-20T14:15:00Z",
  "data": {
    "document_id": "doc_456789",
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "rejection_reasons": [
      {"code": "document_expired", "message": "Document has expired"},
      {"code": "poor_quality", "message": "Image quality too low"}
    ]
  }
}

Biometric Events​

biometric.captured​

Triggered when biometric data is captured.

{
  "id": "evt_123464",
  "type": "biometric.captured",
  "created_at": "2025-01-20T14:20:00Z",
  "data": {
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "biometric_type": "face",
    "liveness_check": true
  }
}

biometric.verified​

Triggered when biometric verification completes.

{
  "id": "evt_123465",
  "type": "biometric.verified",
  "created_at": "2025-01-20T14:22:00Z",
  "data": {
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "face_match": {
      "status": "match",
      "confidence": 98.5
    },
    "liveness": {
      "status": "live",
      "confidence": 99.2
    }
  }
}

biometric.failed​

Triggered when biometric verification fails.

{
  "id": "evt_123466",
  "type": "biometric.failed",
  "created_at": "2025-01-20T14:22:00Z",
  "data": {
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "failure_reasons": [
      {"code": "face_mismatch", "message": "Face does not match document photo"},
      {"code": "liveness_failed", "message": "Liveness check failed"}
    ]
  }
}

Screening Events​

screening.completed​

Triggered when screening check completes.

{
  "id": "evt_123467",
  "type": "screening.completed",
  "created_at": "2025-01-20T14:25:00Z",
  "data": {
    "check_id": "check_789012",
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "check_types": ["sanctions", "pep", "adverse_media"],
    "status": "clear",
    "hit_count": 0
  }
}

screening.hit​

Triggered when a screening hit is found.

{
  "id": "evt_123468",
  "type": "screening.hit",
  "created_at": "2025-01-20T14:25:00Z",
  "data": {
    "check_id": "check_789012",
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "hit_type": "sanctions",
    "hit_count": 1,
    "hits": [
      {
        "hit_id": "hit_345678",
        "matched_name": "JOHN DOE",
        "list_source": "ofac_sdn",
        "confidence": 92.5,
        "resolution_status": "pending"
      }
    ],
    "case_id": "case_789012"
  }
}

screening.hit_resolved​

Triggered when a screening hit is resolved.

{
  "id": "evt_123469",
  "type": "screening.hit_resolved",
  "created_at": "2025-01-20T15:00:00Z",
  "data": {
    "hit_id": "hit_345678",
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "resolution": "false_positive",
    "resolved_by": "analyst@company.com",
    "resolution_notes": "Different individual - DOB mismatch"
  }
}

screening.monitoring_alert​

Triggered by ongoing monitoring.

{
  "id": "evt_123470",
  "type": "screening.monitoring_alert",
  "created_at": "2025-01-20T16:00:00Z",
  "data": {
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "alert_type": "new_adverse_media",
    "details": {
      "source": "Reuters",
      "headline": "Company CEO involved in fraud investigation",
      "published_at": "2025-01-20"
    },
    "case_id": "case_789013"
  }
}

Case Events​

case.created​

Triggered when a new case is created.

{
  "id": "evt_123471",
  "type": "case.created",
  "created_at": "2025-01-20T14:30:00Z",
  "data": {
    "case_id": "case_789012",
    "type": "sanctions",
    "priority": "critical",
    "subject": {
      "type": "applicant",
      "id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "title": "OFAC sanctions match"
  }
}

case.assigned​

Triggered when a case is assigned.

{
  "id": "evt_123472",
  "type": "case.assigned",
  "created_at": "2025-01-20T14:35:00Z",
  "data": {
    "case_id": "case_789012",
    "assigned_to": {
      "user_id": "user_456",
      "email": "analyst@company.com"
    },
    "assigned_by": "auto_routing"
  }
}

case.status_changed​

Triggered when case status changes.

{
  "id": "evt_123473",
  "type": "case.status_changed",
  "created_at": "2025-01-20T15:00:00Z",
  "data": {
    "case_id": "case_789012",
    "previous_status": "open",
    "new_status": "in_progress",
    "changed_by": "analyst@company.com"
  }
}

case.resolved​

Triggered when a case is resolved.

{
  "id": "evt_123474",
  "type": "case.resolved",
  "created_at": "2025-01-20T16:00:00Z",
  "data": {
    "case_id": "case_789012",
    "resolution": "no_action_required",
    "resolution_notes": "False positive - different individual",
    "resolved_by": "analyst@company.com",
    "applicant_action": "approved"
  }
}

case.escalated​

Triggered when a case is escalated.

{
  "id": "evt_123475",
  "type": "case.escalated",
  "created_at": "2025-01-20T15:30:00Z",
  "data": {
    "case_id": "case_789012",
    "escalated_to": "senior_analyst@company.com",
    "escalation_reason": "Complex ownership structure requires senior review",
    "escalated_by": "analyst@company.com"
  }
}

Company Events (KYB)​

company.created​

Triggered when a company is created.

{
  "id": "evt_123476",
  "type": "company.created",
  "created_at": "2025-01-20T14:00:00Z",
  "data": {
    "company_id": "660e8400-e29b-41d4-a716-446655440001",
    "legal_name": "Acme Corporation Ltd",
    "registration_number": "12345678",
    "incorporation_country": "USA"
  }
}

company.verified​

Triggered when company verification completes.

{
  "id": "evt_123477",
  "type": "company.verified",
  "created_at": "2025-01-20T15:00:00Z",
  "data": {
    "company_id": "660e8400-e29b-41d4-a716-446655440001",
    "verification_status": "verified",
    "registry_match": true,
    "ubo_count": 3,
    "ubos_verified": 3
  }
}

company.ubo_added​

Triggered when a beneficial owner is added.

{
  "id": "evt_123478",
  "type": "company.ubo_added",
  "created_at": "2025-01-20T14:30:00Z",
  "data": {
    "company_id": "660e8400-e29b-41d4-a716-446655440001",
    "ubo_id": "ubo_789",
    "name": "John Doe",
    "ownership_percentage": 40,
    "verification_status": "pending"
  }
}

Event Categories Summary​

CategoryEvents
Applicantcreated, updated, verified, rejected, pending_review
Documentuploaded, verified, rejected
Biometriccaptured, verified, failed
Screeningcompleted, hit, hit_resolved, monitoring_alert
Casecreated, assigned, status_changed, resolved, escalated
Companycreated, verified, ubo_added

Subscribing to Events​

curl -X POST https://api.bytrustgate.com/v1/webhooks \
  -H "Authorization: Bearer tg_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks",
    "events": [
      "applicant.verified",
      "applicant.rejected",
      "screening.hit",
      "case.created"
    ]
  }'

Wildcard Subscriptions​

{
  "events": [
    "applicant.*",
    "screening.*",
    "case.*"
  ]
}

Next Steps​