---
title: "Customer status change"
method: POST
path: "customer-update"
tags: ["Webhooks"]
---

# Customer status change

`POST customer-update` (webhook)

Webhook that is called when the status of a customer is updated, including KYC and KYB status changes.
This endpoint should be implemented by clients of the Grid API.

### Authentication
The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid.
To verify the signature:
1. Get the Grid API public key provided to you during integration
2. Decode the base64 signature from the header
3. Create a SHA-256 hash of the request body
4. Verify the signature using the public key and the hash

If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

## Payload

- CustomerWebhook
  - `id` string, required — Unique identifier for this webhook delivery (can be used for idempotency)
  - `type` 'CUSTOMER.KYC_APPROVED' | 'CUSTOMER.KYC_REJECTED' | 'CUSTOMER.KYC_PENDING' | 'CUSTOMER.KYB_APPROVED' | 'CUSTOMER.KYB_REJECTED' | 'CUSTOMER.KYB_PENDING', required — Type of webhook event in OBJECT.EVENT dot-notation. The part before the dot identifies the resource, the part after identifies the event. This lets consumers route purely on type without inspecting data.status.
  - `timestamp` string, date-time, required — ISO 8601 timestamp of when the webhook was sent
  - `data` union, required
    - IndividualCustomer
      - `id` string — System-generated unique identifier
      - `platformCustomerId` string, required — Platform-specific customer identifier
      - `region` string — Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction.
      - `currencies` string[] — List of currency codes enabled for this customer.
      - `email` string, email — Email address for the customer.
      - `umaAddress` string, required — Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer.
      - `createdAt` string, date-time — Creation timestamp
      - `updatedAt` string, date-time — Last update timestamp
      - `isDeleted` boolean — Whether the customer is marked as deleted
      - `customerType` 'INDIVIDUAL', required
      - `kycStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' — The current KYC status of a customer
      - `fullName` string — Individual's full name
      - `birthDate` string, date — Date of birth in ISO 8601 format (YYYY-MM-DD)
      - `nationality` string — Country code (ISO 3166-1 alpha-2)
      - `address` Address
        - `line1` string, required — Street address line 1
        - `line2` string — Street address line 2
        - `city` string — City
        - `state` string — State/Province/Region
        - `postalCode` string, required — Postal/ZIP code
        - `country` string, required — Country code (ISO 3166-1 alpha-2)
    - BusinessCustomer
      - `id` string — System-generated unique identifier
      - `platformCustomerId` string, required — Platform-specific customer identifier
      - `region` string — Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction.
      - `currencies` string[] — List of currency codes enabled for this customer.
      - `email` string, email — Email address for the customer.
      - `umaAddress` string, required — Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer.
      - `createdAt` string, date-time — Creation timestamp
      - `updatedAt` string, date-time — Last update timestamp
      - `isDeleted` boolean — Whether the customer is marked as deleted
      - `customerType` 'BUSINESS', required
      - `kybStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' — The current KYB status of a business customer
      - `address` Address
        - `line1` string, required — Street address line 1
        - `line2` string — Street address line 2
        - `city` string — City
        - `state` string — State/Province/Region
        - `postalCode` string, required — Postal/ZIP code
        - `country` string, required — Country code (ISO 3166-1 alpha-2)
      - `businessInfo` object — Business information returned on a customer. `taxId` and `incorporatedOn` are required on creation but may be absent on legacy customers that pre-date the requirement, so both are optional in responses.
        - `legalName` string, required — Legal name of the business
        - `doingBusinessAs` string — Trade name or DBA name of the business, if different from the legal name
        - `country` string — Country of incorporation or registration (ISO 3166-1 alpha-2)
        - `registrationNumber` string — Business registration number
        - `incorporatedOn` string, date — Date of incorporation in ISO 8601 format (YYYY-MM-DD)
        - `entityType` 'SOLE_PROPRIETORSHIP' | 'PARTNERSHIP' | 'LLC' | 'CORPORATION' | 'S_CORPORATION' | 'NON_PROFIT' | 'OTHER' — Legal entity type of the business
        - `taxId` string — Tax identification number
        - `countriesOfOperation` string[] — List of countries where the business operates (ISO 3166-1 alpha-2)
        - `businessType` 'AGRICULTURE_FORESTRY_FISHING_AND_HUNTING' | 'MINING_QUARRYING_AND_OIL_AND_GAS_EXTRACTION' | 'UTILITIES' | 'CONSTRUCTION' | 'MANUFACTURING' | 'WHOLESALE_TRADE' | 'RETAIL_TRADE' | 'TRANSPORTATION_AND_WAREHOUSING' | 'INFORMATION' | 'FINANCE_AND_INSURANCE' | 'REAL_ESTATE_AND_RENTAL_AND_LEASING' | 'PROFESSIONAL_SCIENTIFIC_AND_TECHNICAL_SERVICES' | 'MANAGEMENT_OF_COMPANIES_AND_ENTERPRISES' | 'ADMINISTRATIVE_AND_SUPPORT_AND_WASTE_MANAGEMENT_AND_REMEDIATION_SERVICES' | 'EDUCATIONAL_SERVICES' | 'HEALTH_CARE_AND_SOCIAL_ASSISTANCE' | 'ARTS_ENTERTAINMENT_AND_RECREATION' | 'ACCOMMODATION_AND_FOOD_SERVICES' | 'OTHER_SERVICES' | 'PUBLIC_ADMINISTRATION' — The high-level industry category of the business
        - `purposeOfAccount` 'CONTRACTOR_PAYOUTS' | 'CREATOR_PAYOUTS' | 'EMPLOYEE_PAYOUTS' | 'MARKETPLACE_SELLER_PAYOUTS' | 'SUPPLIER_PAYMENTS' | 'CROSS_BORDER_B2B' | 'AR_AUTOMATION' | 'AP_AUTOMATION' | 'EMBEDDED_PAYMENTS' | 'PLATFORM_FEE_COLLECTION' | 'P2P_TRANSFERS' | 'CHARITABLE_DONATIONS' | 'OTHER' — The intended purpose for using the Grid account
        - `sourceOfFunds` string — The primary source of funds for the business
        - `expectedMonthlyTransactionCount` 'COUNT_UNDER_10' | 'COUNT_10_TO_100' | 'COUNT_100_TO_500' | 'COUNT_500_TO_1000' | 'COUNT_OVER_1000' — Expected number of transactions per month
        - `expectedMonthlyTransactionVolume` 'VOLUME_UNDER_10K' | 'VOLUME_10K_TO_100K' | 'VOLUME_100K_TO_1M' | 'VOLUME_1M_TO_10M' | 'VOLUME_OVER_10M' — Expected total transaction volume per month in USD equivalent
        - `expectedRecipientJurisdictions` string[] — List of countries where the business expects to send payments (ISO 3166-1 alpha-2)
      - `beneficialOwners` BeneficialOwner[]
        - `id` string, required — Unique identifier for this beneficial owner
        - `customerId` string, required — The ID of the business customer this beneficial owner is associated with
        - `roles` BeneficialOwnerRole[], required — Roles of this person within the business
        - `ownershipPercentage` integer, required — Percentage of ownership in the business (0-100)
        - `personalInfo` BeneficialOwnerPersonalInfo, required
          - `firstName` string, required — First name of the individual
          - `middleName` string — Middle name of the individual
          - `lastName` string, required — Last name of the individual
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country of nationality (ISO 3166-1 alpha-2)
          - `email` string, email — Email address of the individual
          - `phoneNumber` string — Phone number in E.164 format
          - `address` Address, required
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `idType` 'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID', required — Type of tax identification
          - `identifier` string, required — The identification number or value
          - `countryOfIssuance` string — Country that issued the identification (ISO 3166-1 alpha-2)
        - `kycStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED', required — The current KYC status of a customer
        - `createdAt` string, date-time, required — When this beneficial owner was created
        - `updatedAt` string, date-time — When this beneficial owner was last updated

## Acknowledgement `200`

Webhook received successfully

## Other responses

- `400` — Bad request
- `401` — Unauthorized - Signature validation failed
- `409` — Conflict - Webhook has already been processed (duplicate id)

---

[API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) · [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lightsparkdev/grid-api/revisions/d0bce562bffd/schema)