# Person Events

GrailPay emits webhook events when key lifecycle changes occur for individual users, referred to as People in the platform. These events notify you in real time when a person is created or updated, enabling you to synchronize user records across your systems, trigger onboarding processes, or verify changes in identity-related data.

While people may be linked to a business or merchant, they can also exist independently as participants in ACH transactions. Each webhook payload includes unique identifiers and metadata to help you track a person's lifecycle within your platform and respond appropriately to changes in their profile.

All payloads below are shown in full, including the [event envelope](/docs/technical/webhooks/events/#event-envelope).

***

## `person.created`

This webhook is triggered whenever a new individual user is added to the platform, either as part of onboarding or through a standalone user creation flow.

```json title="Event"
{
  "event": "person.created",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "person": {
      "client_reference_id": "person_98345",
      "uuid": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e",
      "status": "APPROVED",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "test@grailpay.com",
      "phone": "1234567890",
      "address": {
        "line_1": "123 Main St",
        "line_2": "Apt 4B",
        "city": "Denver",
        "state": "CO",
        "zip": "80203"
      },
      "payout_type": "individual",
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      }
    },
    "bank_account": {
      "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
      "aggregator_type": "manual",
      "provider_type": "manual",
      "account_name": "Acme, Inc",
      "account_type": "checking",
      "account_number": "1111222233330000",
      "routing_number": "011401533",
      "institution_name": "Bank of America",
      "aggregator": "mx",
      "is_default": true,
      "client_reference_id": "client-1234",
      "status": "connected",
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      }
    }
  }
}
```

## `person.updated`

This webhook is triggered whenever an existing user's information is modified in the GrailPay platform. This includes changes to core fields such as name, email, phone number, or address.

```json title="Event"
{
  "event": "person.updated",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "person": {
      "client_reference_id": "person_98345",
      "uuid": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e",
      "status": "APPROVED",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "test@grailpay.com",
      "phone": "1234567890",
      "address": {
        "line_1": "123 Main St",
        "line_2": "Apt 4B",
        "city": "Denver",
        "state": "CO",
        "zip": "80203"
      },
      "payout_type": "individual",
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      }
    },
    "bank_account": {
      "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
      "aggregator_type": "manual",
      "provider_type": "manual",
      "account_name": "Acme, Inc",
      "account_type": "checking",
      "account_number": "1111222233330000",
      "routing_number": "011401533",
      "institution_name": "Bank of America",
      "aggregator": "mx",
      "is_default": true,
      "client_reference_id": "client-1234",
      "status": "connected",
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      }
    }
  }
}
```

## `person.status_changed`

This webhook is triggered whenever a person's status is updated within the GrailPay platform due to risk, compliance, or business rules. Status changes may include transitions such as `ON_HOLD_FRAUD_PAYEE`, `ON_HOLD_SANCTIONS`, or other states that restrict the person's ability to transact. These updates typically occur when GrailPay identifies a risk-related reason to suspend or restrict activity for an individual user. This webhook allows your system to respond immediately, by disabling UI elements, blocking actions, or initiating internal support workflows.

```json title="Event"
{
  "event": "person.status_changed",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "person": {
      "client_reference_id": "person_98345",
      "uuid": "7c41f6a2-a4b9-4df8-9225-2c1b7312042e",
      "status": "ON_HOLD_FRAUD_PAYEE",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "test@grailpay.com",
      "phone": "1234567890",
      "address": {
        "line_1": "123 Main St",
        "line_2": "Apt 4B",
        "city": "Denver",
        "state": "CO",
        "zip": "80203"
      },
      "payout_type": "individual",
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      }
    },
    "change_reason": "fraud_related_return",
    "outcome": "This person and its associated entities will no longer be able to transact within our payments api.",
    "action": "Contact support@grailpay.com to resolve the issue.",
    "relations": {
      "merchant": {
        "uuid": "fae2de1a-68c9-43a0-9c63-4daf8d16a709"
      }
    }
  }
}
```