Verification webhooks

Agio sends KYC review and wallet verification updates to your server. These endpoints are configured by the Agio team. Card partners use separate card webhook subscriptions.

Configure an endpoint

Create an HTTPS endpoint that accepts POST requests with a JSON body, then contact Agio to configure delivery to it. Associate updates with your records using externalUserId for KYC or external_user_id for wallet verification.

KYC webhook

KYC webhooks report review changes for an applicant. Use reviewStatus for review progress and reviewResult for the decision.

KYC webhook fields

Field	Meaning
WebhookPayloadId	Agio webhook payload ID
applicantId	Verification provider applicant ID
externalUserId	User identifier supplied by your application
inspectionId	Verification inspection ID
correlationId	Provider request correlation ID
type	Webhook event type
levelName	Verification level
reviewStatus	Current review state
reviewResult	Review decision and rejection details
reviewApproved	Agio approval summary, when present
sandboxMode	Whether the event comes from the sandbox
createdAt	Event creation time

Other fields depend on the event and applicant type.

Read the decision

A completed review has a decision in reviewResult.reviewAnswer: GREEN means approved and RED means rejected. For rejection, reviewRejectType distinguishes RETRY from FINAL; rejectLabels lists the reasons. See verification results for all review states.

When present, reviewApproved: true summarizes approval. A false value can also mean that review is still pending; read the review fields before treating it as a final rejection.

Example initial rejection

{
  "WebhookPayloadId": 1,
  "applicantId": "5cb744200a975a67ed1798a4",
  "inspectionId": "5cb744200a975a67ed1798a5",
  "correlationId": "req-fa94263f-0b23-42d7-9393-ab10b28ef42d",
  "externalUserId": "externalUserId",
  "levelName": "basic-kyc-level",
  "type": "applicantReviewed",
  "reviewResult": {
    "reviewAnswer": "RED",
    "moderationComment": "We do not accept screenshots. Please upload an original photo.",
    "clientComment": "Screenshots are not accepted.",
    "reviewRejectType": "RETRY",
    "rejectLabels": ["UNSATISFACTORY_PHOTOS", "SCREENSHOTS"]
  },
  "reviewStatus": "completed",
  "createdAt": "2026-02-21 13:23:19+0000"
}

Example final rejection

{
  "WebhookPayloadId": 1,
  "applicantId": "5cb744200a975a67ed1798a4",
  "inspectionId": "5cb744200a975a67ed1798a5",
  "correlationId": "req-fa94263f-0b23-42d7-9393-ab10b28ef42d",
  "externalUserId": "externalUserId",
  "levelName": "basic-kyc-level",
  "type": "applicantReviewed",
  "reviewResult": {
    "moderationComment": "We could not verify your profile. Please contact support: [email protected]",
    "clientComment": " Suspected fraudulent account.",
    "reviewAnswer": "RED",
    "rejectLabels": ["UNSATISFACTORY_PHOTOS", "GRAPHIC_EDITOR", "FORGERY"],
    "reviewRejectType": "FINAL"
  },
  "reviewStatus": "completed",
  "createdAt": "2026-02-21 13:23:19+0000"
}

Example final approval

{
  "applicantId": "5cb56e8e0a975a35f333cb83",
  "inspectionId": "5cb56e8e0a975a35f333cb84",
  "correlationId": "req-a260b669-4f14-4bb5-a4c5-ac0218acb9a4",
  "externalUserId": "externalUserId",
  "levelName": "basic-kyc-level",
  "type": "applicantReviewed",
  "reviewResult": {
    "reviewAnswer": "GREEN"
  },
  "reviewStatus": "completed",
  "createdAt": "2026-02-21 13:23:19+0000"
}

KYT webhook

Wallet verification webhooks report changes to the wallet whitelisting decision.

KYT webhook data fields

Field	Type	Description
id	integer	Unique identifier for the wallet record
wallet_address	string	The wallet address that was analyzed
external_user_id	string	Your internal user identifier
status_id	integer	Current wallet status (see below)
clean_wallet	boolean	Whether the wallet was marked as clean (new wallet with no history)
created_at	timestamp	When the wallet was submitted for analysis
updated_at	timestamp	When the status was last updated

Wallet status codes

Status ID	Status	Description
1	Pending	Wallet is being analyzed
2	Approved	Wallet passed risk analysis and manual review
3	Denied	Wallet failed risk analysis (high risk score, sanctioned addresses, illicit funds)
4	Auto-approved	Wallet passed automated risk analysis (low risk score)

Example KYT webhook payload

{
  "id": 12345,
  "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
  "external_user_id": "user-abc-123",
  "status_id": 4,
  "clean_wallet": false,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:31:45Z"
}

Approved, denied, and auto-approved are final results. See wallet verification for the clean_wallet flag and status definitions.