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.

---

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.

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.

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.

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"
      }
    }
  }
}