Skip to main content

​
Overview

The customer.created webhook is triggered when a new customer is created in your Metrifox account.

​
When It’s Triggered

This event is sent immediately after a customer is successfully created through:
  • The Metrifox API (POST /api/v1/customers)
  • CSV upload
  • Any other customer creation method

​
Payload Structure

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "customer.created",
  "created_at": 1704067200000,
  "data": {
    "customer": "// See customer object below"
  }
}

​
Customer Object

{
  "id": "4cea9f47-95ad-4026-a36d-d24eff9925b3",
  "customer_type": 1,
  "customer_key": "DEV-A35FA0WOS",
  "email_addresses": [
    {
      "email": "cj@gmail.com",
      "is_primary": true
    }
  ],
  "phone_numbers": [
    {
      "is_primary": true,
      "country_code": "+234",
      "phone_number": "+2348123456789"
    }
  ],
  "deleted_at": "2026-02-10T08:42:08.322Z",
  "tenant_id": "b1b7b362-5c5c-48a5-9454-94c3c4d3e5b3",
  "created_at": "2026-02-09T08:42:08.322Z",
  "updated_at": "2026-02-09T08:42:08.322Z",
  "otp": "123456",
  "otp_sent_at": "2026-02-09T08:40:00.000Z",
  "verified_at": "2026-02-09T08:41:30.000Z",
  "source": "manual",
  "edit_token": "cfd3b3fc-fce3-4bb8-b200-380bd98283fe",
  "edit_token_expires_at": "2026-02-09T09:40:00.000Z",
  "primary_email": "cj@gmail.com",
  "primary_phone": "+2348123456789",
  "legal_name": "Charlie Jones Ltd",
  "display_name": "Charlie Jones",
  "first_name": "Charlie",
  "last_name": "Jones",
  "middle_name": "A.",
  "legal_number": "RC-1234567",
  "tax_identification_number": "NG-TIN-1234567",
  "logo_url": "https://cdn.example.com/logos/customer.png",
  "website_url": "https://www.example.com",
  "timezone": "UTC+00:00",
  "language": "english",
  "currency": "USD",
  "tax_status": 1,
  "billing_email": "cj@gmail.com",
  "address_line1": "294 Herbert Macaulay Way",
  "address_line2": "Suite 12B",
  "city": "Yaba",
  "state": "Lagos",
  "country": "nigeria",
  "zip_code": "100001",
  "shipping_address_line1": "294 Herbert Macaulay Way",
  "shipping_address_line2": "Suite 12B",
  "shipping_city": "Yaba",
  "shipping_state": "Lagos",
  "shipping_country": "nigeria",
  "shipping_zip_code": "100001",
  "account_manager": "Account manager",
  "date_of_birth": "1985-06-15",
  "billing_configuration": {
    "billing_address": "294 Herbert Macaulay Way, Yaba, Lagos 100001",
    "billing_email": "billing@services.com",
    "payment_reminder_days": 3,
    "preferred_payment_gateway": "paystack",
    "preferred_payment_method": "card"
  },
  "tax_identifications": [
    {
      "type": "TIN",
      "number": "1233423",
      "country": "nigeria"
    }
  ],
  "contact_people": [
    {
      "is_primary": true,
      "first_name": "Contact",
      "last_name": "Person",
      "email_address": "contact@services.com",
      "designation": "Manager",
      "department": "People",
      "phone_number": "+234812324532"
    }
  ],
  "payment_terms": {
    "type": "on_receipt",
    "value": 0
  },
  "metadata": {
    "notes": "notes",
    "external_id": "12334534",
    "preferences": {
      "communication_channels": [
        {
          "url": "https://www.facebook.com/example",
          "name": "Facebook"
        }
      ]
    }
  },
  "mid_cycle_invoice_consolidation": false
}

​
Customer Data Fields

The data.customer object contains the full customer record with all fields, including:
  • id: Internal customer ID
  • customer_type: Either individual or business
  • customer_key: The unique customer key (immutable)
  • email_addresses: Email addresses
  • phone_numbers: Phone numbers
  • deleted_at: Deletion timestamp (if deleted)
  • tenant_id: The tenant ID this customer belongs to
  • created_at: Timestamp when the customer was created
  • updated_at: Timestamp when the customer was last updated
  • otp: One-time password value (if applicable)
  • otp_sent_at: OTP sent timestamp (if applicable)
  • verified_at: Verification timestamp (if applicable)
  • source: Source of the customer record (e.g., manual)
  • edit_token: Edit token (if applicable)
  • edit_token_expires_at: Edit token expiration timestamp
  • primary_email: Primary email address
  • primary_phone: Primary phone number
  • legal_name: Registered legal name
  • display_name: Display name shown in the UI
  • first_name: First name
  • last_name: Last name
  • middle_name: Middle name
  • legal_number: Legal registration number
  • tax_identification_number: Primary tax ID number
  • logo_url: Logo URL
  • website_url: Website URL
  • timezone: Customer timezone
  • language: Preferred language
  • currency: Customer currency
  • tax_status: Tax status (enum)
  • billing_email: Billing email address for invoices
  • address_line1: Primary address line 1
  • address_line2: Primary address line 2
  • city: Customer’s city
  • state: Customer’s state or region
  • country: Customer’s country
  • zip_code: Postal code
  • shipping_address_line1: Shipping address line 1
  • shipping_address_line2: Shipping address line 2
  • shipping_city: Shipping city
  • shipping_state: Shipping state or region
  • shipping_country: Shipping country
  • shipping_zip_code: Shipping postal code
  • account_manager: Assigned account manager
  • date_of_birth: Customer date of birth (ISO date)
  • billing_configuration: Billing configuration object
  • tax_identifications: List of tax IDs
  • contact_people: List of contact people for the customer
  • payment_terms: Payment term rules
  • metadata: Custom metadata object
  • mid_cycle_invoice_consolidation: Whether mid-cycle invoices are consolidated

​
Example Use Cases

  • Sync new customers to your CRM system
  • Send welcome emails to new customers
  • Create customer records in external systems
  • Trigger onboarding workflows