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.

---

business.created

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

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.

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