---
title: "User-defined statuses webhook | Veriff.com"
slug: "user-defined-statuses-webhook"
description: "Learn how to set up user-defined statuses webhooks in the Veriff Customer Portal and receive real-time updates on session statuses."
updated: 2025-02-25T12:53:16Z
published: 2025-02-25T12:53:16Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.veriff.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User-defined statuses webhook

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](https://veriff-dev-documentation.document360.io/docs/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](https://help.veriff.com/en/articles/8480053-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](https://devdocs.veriff.com/docs/signing-up) and [Log in](https://devdocs.veriff.com/docs/logging-in) articles
2. Set up webhook URL(s) **on your side**and have them at hand
  1. Make sure they **match** the [Webhook URL](https://devdocs.veriff.com/docs/webhooks-guide#webhook-url-requirements) requirements
  2. Make sure your system is **able to handle** [Webhooks receipt, delivery and resending](https://devdocs.veriff.com/docs/webhooks-guide#webhook-delivery-receipt-and-resending) requirements
  3. Check the [Webhooks headers and payload](https://devdocs.veriff.com/docs/webhooks-guide#webhooks-headers-and-payload) section for info
3. Secure your communication, check the [HMAC Authentication and Endpoint Security](https://devdocs.veriff.com/docs/hmac-authentication-and-endpoint-security) article
4. Make sure your system is **able to handle** the [Backwards compatible changes](https://devdocs.veriff.com/docs/backwards-compatible-changes)

5.Proceed to [User-defined statuses webhook setup](/v1/docs/user-defined-statuses-webhook#userdefined-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](https://veriff-dev-documentation.document360.io/docs/webhooks-guide#set-up-webhooks) sub-section for detailed overview of the setup process*

---

## Sample request

```json
{
    "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

- [Webhooks Guide](/webhooks-guide.md)