# Business Events

GrailPay emits webhook events when key lifecycle changes occur for business entities within the platform. These events notify you in real time when a business is created or updated, allowing you to synchronize entity data across your systems, trigger onboarding workflows, or audit compliance checkpoints as part of your Payments integration.

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

***

## `business.created`

This webhook is triggered whenever a new Business entity is successfully created within the GrailPay system.

```json title="Event"
{
  "event": "business.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": {
    "business": {
      "uuid": "866db83c-3e5e-48d4-8221-d29eaf6471e5",
      "business_type": "business",
      "name": "Acme, Inc.",
      "trading_name": "Acme Corp",
      "payout_type": "individual",
      "client_reference_id": "bus_123456789",
      "address": {
        "line_1": "123 Main St",
        "line_2": "Apt 4B",
        "city": "Denver",
        "state": "CO",
        "zip": "80203"
      },
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      }
    },
    "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"
      }
    }
  }
}
```

## `business.updated`

This webhook is triggered whenever a business entity is updated within the GrailPay system. Updates may include changes to KYB information, business name, address, or other identifying details.

```json title="Event"
{
  "event": "business.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": {
    "business": {
      "uuid": "866db83c-3e5e-48d4-8221-d29eaf6471e5",
      "business_type": "business",
      "name": "Acme, Inc.",
      "trading_name": "Acme Corp",
      "payout_type": "individual",
      "client_reference_id": "bus_123456789",
      "address": {
        "line_1": "123 Main St",
        "line_2": "Apt 4B",
        "city": "Denver",
        "state": "CO",
        "zip": "80203"
      },
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      }
    },
    "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"
      }
    }
  }
}
```