> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axisfi.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

# Webhooks

Subscribe to real-time event notifications for transfers, customers, and recipient status changes.

## Overview

AxisFI uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like bank transfers or KYC identity verification, allowing you to trigger backend actions without constant API polling.

### Security & Signature Verification

To ensure that a request is genuinely sent by AxisFI, each webhook includes an `X-Webhook-Signature` in the header.

> **Best Practice:** We strongly recommend verifying the HMAC-SHA256 signature using your account's `Webhook Secret` before processing any data.

***

## Event Types

### **Transfers**

Stay updated on the lifecycle of individual or batch transfers.

| **Event**            | **Description**                                                                        |
| -------------------- | -------------------------------------------------------------------------------------- |
| `transfer.completed` | Triggered when the transfer is successfully completed and funds reach the destination. |
| `transfer.failed`    | Triggered if a transfer is rejected due to insufficient funds or compliance issues.    |

**Payload examples**

The **data** object is the same as the response body of [Transfer](http://localhost:3000/api-reference/transfer/transfer). See example below.

```json theme={null}
{
  "transaction_type": "transfer",
  "transaction_id": "txn_e7f5c7fb52df499e90b59e5f57448eca",
  "partner_transaction_id": "INV_LOGI_2026_001",
  "source": {
    "currency": "USDT",
    "network": "ETH",
    "amount": 5000.00
  },
  "target": {
    "currency": "USD",
    "network": null,
    "amount": 4985.50
  },
  "status": "Succeeded",
  "customer_id": null,
  "recipient_id": null,
  "exchange_rate": 0.999,
  "fee": 9.50,
  "purpose_code": "SERVICES_PAYMENT",
  "notes": "Q1 2026 Warehousing and Fulfillment Service Fees",
  "created_at": "2026-04-02T11:18:03Z",
  "audit_at": "2026-04-02T11:20:00Z",
  "completed_at": "2026-04-02T11:30:00Z",
  "customer": {
    "customer_id": "cus_e2ddee0e7d45490995b4cba6712c6833",
    "partner_customer_id": "AXIS_USER_001",
    "status": "Succeeded",
    "created_at": "2026-01-10T08:00:00Z",
    "business_details": {
      "business_name": "xxx Solutions LLC",
      "business_name_english": "xxx Solutions LLC",
      "business_type": "Limited Liability Company",
      "website": "https://xxxx.com",
      "business_identifier_type": "Business Registration",
      "business_identifier_number": "12-3456789",
      "business_identifier_country_code": "US",
      "business_identifier_start_date": "2020-05-12T00:00:00Z",
      "business_identifier_expiry_date": "2040-05-11T00:00:00Z",
      "business_identifier_document_list": [
        "doc_7bf2b61dc5b24295bd37e548af764e03"
      ]
    },
    "account_usage": {
      "operating_country": "US",
      "goods_service_description": "Financial Services",
      "industry_category_code": "5311",
      "account_usage_product_reference": "Financial Services",
      "estimated_monthly_revenue_currency": "USD",
      "estimated_monthly_revenue_amount": 50000
    },
    "registration_address": {
      "registration_address_line1": "1209 Orange Street",
      "registration_address_city": "Wilmington",
      "registration_address_state": "DE",
      "registration_address_postcode": "19801",
      "registration_address_country_code": "US"
    },
    "primary_contact": {
      "contact_phone": "+12025550178",
      "contact_email": "derek@gmail.test"
    },
    "business_person_list": [
      {
        "basic_info": {
          "first_name": "James",
          "first_name_english": "James",
          "last_name": "Miller",
          "last_name_english": "Miller",
          "birth_date": "1988-03-22T00:00:00Z",
          "nationality": "US",
          "role_type": "CEO",
          "contact_phone": "+12025550178",
          "contact_email": "derek@gmail.test"
        },
        "residential_address": {
          "residential_address_line1": "742 Evergreen Terrace",
          "residential_address_city": "Springfield",
          "residential_address_postcode": "62704",
          "residential_address_country_code": "US",
          "residential_address_state": "IL"
        },
        "identification": {
          "id_type": "National ID",
          "id_number": "919998876655",
          "id_issuing_country_code": "US",
          "id_expiration_date": "2032-05-15T00:00:00Z",
          "id_issue_date": "2022-05-15T00:00:00Z",
          "id_document_front_file_id": "doc_7bf2b61dc5b24295bd37e548af764e04",
          "id_document_back_file_id": "doc_7bf2b61dc5b24295bd37e548af764e05"
        }
      }
    ]
  },
  "recipient": {
    "recipient_id": "rcp_ebb26e5bf5d744fdbd7676c023bb84bd",
    "partner_recipient_id": "VENDOR_LOGI_001",
    "status": "Succeeded",
    "name": "xxxx Solutions Inc",
    "type": "enterprise",
    "country_code": "US",
    "website": "https://globallogistics.test",
    "created_at": "2026-03-20T09:15:00Z",
    "address_info": {
      "address_line_1": "456 Commerce Way",
      "address_line_2": "Suite 200",
      "city": "Los Angeles",
      "state": "CA",
      "post_code": "90001"
    },
    "payment_details": {
      "bank_name": "JPMorgan Chase",
      "network": "SWIFT",
      "payment_method": "INTERNATIONAL_WIRE",
      "account_name": "xxxx Solutions Inc",
      "account_number": "123456789012",
      "swift_code": "CHASUS33",
      "account_currency": "USD",
      "country_code": "US",
      "local_bank_code": "021000021"
    },
    "file_id_list": [
      "doc_7bf2b61dc5b24295bd37e548af764e06"
    ]
  },
  "file_id_list": [
    "doc_7bf2b61dc5b24295bd37e548af764e07"
  ]
}
```

### Deposit

Triggered when external funds are detected entering your wallet address

| **Event**           | **Description**                                                              |
| ------------------- | ---------------------------------------------------------------------------- |
| `deposit.completed` | Triggered when the deposit is confirmed and added to your available balance. |
| `deposit.failed`    | Triggered if a deposit is flagged or fails to settle.                        |

**Payload examples**

The **data** object is the same as the response body of [Create Deposit](https://axisfi.mintlify.app/api-reference/transactions/get-transaction-details). See example below.

```json theme={null}
{
  "transaction_type": "deposit",
  "partner_transaction_id": "3922F79e2EA7e551dF44BE81115",
  "network": "ETH",
  "account_currency": "USDT",
  "amount": 99.99,
  "transaction_id": "txn_ca72384ab1ce4ddda4d95bb090f30350",
  "source_wallet_address": "0x0A4EBD7Ad3922F79e2EA7e551dF44BE81115eAE3",
  "target_wallet_address": "0xdAcA9A62Cf0326F3b0DC010Df78f7F10B6b71c32",
  "status": "completed",
  "created_at": "2023-11-07T05:31:56Z",
  "audit_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z"
}
```

### Customer

Monitor status changes for customer onboarding and identity verification.

| **Event**            | **Description**                                                           |
| -------------------- | ------------------------------------------------------------------------- |
| `customer.active`    | Triggered when a customer's KYC is approved and the account is activated. |
| `customer.rejected`  | Triggered when a customer's application is denied.                        |
| `customer.suspended` | Triggered if an account is temporarily frozen due to suspicious activity. |

**Payload examples**

The **data** object is the same as the response body of [Create Customer](https://axisfi.mintlify.app/api-reference/transactions/get-transaction-details). See example below.

```json theme={null}
{
  "customer_id": "cus_e052d06117a549e2af5820cb3c74dc7f",
  "partner_customer_id": "USER_2026_001",
  "status": "active",
  "created_at": "2026-04-02T08:30:00Z",
  "business_details": {
    "business_name_english": "AxisFI Solutions LLC",
    "website": "https://axisfi.net",
    "business_identifier_type": "Business Registration",
    "business_identifier_number": "12-3456789",
    "business_name": "AxisFI Solutions LLC",
    "business_type": "Limited Liability Company",
    "business_identifier_country_code": "US",
    "business_identifier_start_date": "2020-05-12T00:00:00Z",
    "business_identifier_expiry_date": "2040-05-11T00:00:00Z",
    "business_identifier_file_id_list": [
      "doc_ein_verification_letter_001",
      "doc_articles_of_organization_002"
    ]
  },
  "account_usage": {
    "operating_country": "US",
    "goods_service_description": "Financial Services.",
    "industry_category_code": "5311",
    "account_usage_product_reference": "Financial Services",
    "estimated_monthly_revenue_currency": "USD",
    "estimated_monthly_revenue_amount": 50000
  },
  "registration_address": {
    "registration_address_line1": "1209 Orange Street",
    "registration_address_city": "Wilmington",
    "registration_address_state": "DE",
    "registration_address_postcode": "19801",
    "registration_address_country_code": "US"
  },
  "primary_contact": {
    "contact_phone": "+8613800138000",
    "contact_email": "derek@axisfi.test"
  },
  "business_person_list": [
    {
      "basic_info": {
        "first_name_english": "James",
        "last_name_english": "Miller",
        "birth_date": "1988-03-22T00:00:00Z",
        "nationality": "US",
        "role_type": "CEO",
        "first_name": "James",
        "last_name": "Miller",
        "contact_phone": "+12025550178",
        "contact_email": "james.miller@axisfi.test"
      },
      "residential_address": {
        "residential_address_line1": "742 Evergreen Terrace",
        "residential_address_city": "Springfield",
        "residential_address_state": "IL",
        "residential_address_postcode": "62704",
        "residential_address_country_code": "US"
      },
      "identification": {
        "id_type": "DRIVERS_LICENSE",
        "id_number": "D123456789",
        "id_issuing_country_code": "US",
        "id_expiration_date": "2032-05-15T00:00:00Z",
        "id_issue_date": "2022-05-15T00:00:00Z",
        "id_document_front_file_id": "file_us_dl_front_882",
        "id_document_back_file_id": "file_us_dl_back_882"
      }
    }
  ]
}
```

### Recipient

Monitor the status of your saved recipients.

| **Event**            | **Description**                                                  |
| -------------------- | ---------------------------------------------------------------- |
| `recipient.active`   | Recipient details are verified and ready for transfers.          |
| `recipient.rejected` | Recipient information is invalid or rejected.                    |
| `recipient.supended` | Recipient has been blacklisted or paused for compliance reasons. |

**Payload examples**

The **data** object is the same as the response body of [Create Recipient](https://axisfi.mintlify.app/api-reference/transactions/get-transaction-details). See example below.

```json theme={null}
{
  "name": "Global Logistics Solutions Inc",
  "type": "enterprise",
  "website": "https://globallogistics.test",
  "recipient_id": "rec_9h2v6kLm4pX",
  "partner_recipient_id": "VENDOR_LOGI_001",
  "status": "active",
  "country_code": "US",
  "created_at": "2026-04-02T09:15:00Z",
  "address_info": {
    "address_line_1": "456 Commerce Way",
    "address_line_2": "Suite 200",
    "city": "Los Angeles",
    "state": "CA",
    "post_code": "90001"
  },
  "payment_details": {
    "account_type": "bank",
    "bank_name": "JPMorgan Chase",
    "network": "SWIFT",
    "payment_method": "INTERNATIONAL_WIRE",
    "account_name": "Global Logistics Solutions Inc",
    "account_number": "123456789012",
    "swift_code": "CHASUS33",
    "account_currency": "USD",
    "country_code": "US",
    "local_bank_code": "021000021"
  },
  "file_id_list": [
    "doc_dc988a1d7dd04f78b24f2bbb20c8ebeb"
  ]
}
```