User-defined statuses webhook

  • Updated on Feb 25, 2025

The webhook returns data after an user has added a status to an attempt in the Veriff Customer Portal. The payload is sent to Webhook URL for sessions statuses set in Station , which you need to set up in the Veriff Customer Portal.

→ See Webhooks Guide > Set up webhooks sub-section for detailed overview of the setup process

To find instructions how to add statuses, log in to Veriff account and see the Adding user-defined Statuses to Sessions [↗]  article in Veriff Knowledge Base.

When is user-defined statuses webhook sent?

The webhook is sent as soon as a user has added a status to an attempt in the Veriff Customer Portal.

Prerequisites

  1.  Make sure you have access to the Veriff Customer Portal
    1. If you do not, see the Getting Started → Sign up and Log in articles
  2.  Set up webhook URL(s) on your side and have them at hand
    1.  Make sure they match the Webhook URL requirements
    2. Make sure your system is able to handle Webhooks receipt, delivery and resending requirements
  3. Secure your communication, check the HMAC Authentication and Endpoint Security article
  4. Make sure your system is able to handle the Backwards compatible changes

5.Proceed to User-defined statuses webhook setup

User-defined statuses webhook setup

  1. Log in to the Veriff Customer Portal

  2. Navigate to the Integrations page via the top menu and open the relevant integration

  3. On the integration's page, select the Settings tab

  4. Under the title Integration settings you see a list of webhooks

  5. Fill in the Webhook URL for sessions statuses set in Station

→ See Webhooks Guide > Set up webhooks sub-section for detailed overview of the setup process

Sample request

{
    "data": {
        "verification": {
            "id": "a1c68aea-7f4d-478d-80ab-ca9356074f69",
            "userDefinedData": {
                "reason": "Looks like velocity abuse",
                "status": "Custom status for suspicious attempt",
                "createdAt": "2023-10-27T09:59:15.090805Z",
                "reasonCode": null,
                "statusCode": "custom_status_for_suspicious_attempt"
            }
        }
    },
    "time": "2023-10-27T10:00:02.998Z",
    "attemptId": "f2270684-8c51-4d03-88eb-dafd43e8b486",
    "eventType": "user-status.created",
    "sessionId": "0b10cb53-4f3b-48af-bd74-60b85354e51f",
    "vendorData": null,
    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
}

Request properties explained

*Required field

  • data: object*

    • verification: object* Array of JSON objects identifying the attempts

      • id: UUID* -v4 of the attempt

      • userDefinedData: object* Describes the custom statuses defined by the user.

        • status: string* Name of the custom status as set in the Veriff Customer Portal

        • statusCode: string* Autogenerated code for the custom status

        • reason: string* Name of the custom reason as set in the Veriff Customer Portal. If the user has selected the "Custom" reason for the status and typed an explanation to the text box, then the explanation is sent in this field.

        • reasonCode: string | null* Autogenerated code for the reason. It is null when the user has selected the "Custom" reason for the status and typed an explanation to the text box. This explanation is sent in the reason parameter.

        • createdAt: string* Timestamp of when the custom status was added, represented as UTC YYYY-MM-DDTHH:MM:SSS+Timezone Offset (ISO 8601)

  • time: string* Timestamp of when the webhook was sent, represented as UTC YYYY-MM-DDTHH:MM:SSS+Timezone Offset (ISO 8601)

  • attemptId: UUID* -v4 of the attempt

  • eventType: string* Indicates the event type, always user-status.created

  • sessionId: UUID* of the session where the attempt belongs to

  • vendorData: string | null* The unique identifier that you created for your end-user. null if not specified

  • endUserId: string | null* The UUID that you created for your end-user. null if not specified

Related articles