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

# Webhooks

> Webhooks enable your application to receive real-time notifications when important events occur, eliminating the need for continuous polling. XentFi sends HTTP POST requests to your configured endpoints with event data.

## Overview

```mermaid theme={null}
flowchart LR
    subgraph XentFi["XentFi Platform"]
        Event[Event Occurs]
        Queue[Event Queue]
        Delivery[Delivery System]
    end

    subgraph YourApp["Your Application"]
        Endpoint[Webhook Endpoint]
        Process[Process Event]
        Response[Return 2xx]
    end

    Event --> Queue
    Queue --> Delivery
    Delivery --> Endpoint
    Endpoint --> Process
    Process --> Response
    Response --> Delivery
```

## Why Use Webhooks?

<CardGroup cols={2}>
  <Card title="⚡ Real-time Updates" icon="zap">
    Receive notifications instantly when events happen
  </Card>

  <Card title="🔄 Automatic Retries" icon="repeat">
    Failed deliveries are automatically retried
  </Card>

  <Card title="🔒 Secure Verification" icon="shield">
    Every webhook includes a signature to verify authenticity
  </Card>

  <Card title="📊 Event Logging" icon="history">
    Complete history of all webhook deliveries
  </Card>

  <Card title="🎯 Selective Events" icon="filter">
    Subscribe only to the events you care about
  </Card>

  <Card title="🚀 Scalable" icon="trending-up">
    Handle high-volume event streams
  </Card>
</CardGroup>

## Event Types

### Address Events

| Event                       | Trigger                    | Description                             |
| --------------------------- | -------------------------- | --------------------------------------- |
| `address.incoming_transfer` | Incoming transfer detected | Address received funds                  |
| `address.created`           | New address created        | Deposit address generated               |
| `address.updated`           | Address updated            | Address configuration changed           |
| `address.swap_executed`     | Swap completed             | Token swap executed successfully        |
| `address.swap_failed`       | Swap failed                | Token swap execution failed             |
| `address.transfer_executed` | Transfer completed         | Transfer executed successfully          |
| `address.transfer_failed`   | Transfer failed            | Transfer execution failed               |
| `address.signed_success`    | Signing successful         | Transaction/message signed successfully |
| `address.signed_failed`     | Signing failed             | Signing operation failed                |

### Master Wallet Events

| Event                      | Trigger                    | Description                                           |
| -------------------------- | -------------------------- | ----------------------------------------------------- |
| `master.incoming_transfer` | Incoming transfer detected | Master wallet received funds                          |
| `master.created`           | New wallet created         | Master wallet generated                               |
| `master.updated`           | Wallet updated             | Master wallet configuration changed                   |
| `master.swap_executed`     | Swap completed             | Master wallet swap executed successfully              |
| `master.swap_failed`       | Swap failed                | Master wallet swap execution failed                   |
| `master.transfer_executed` | Transfer completed         | Master wallet transfer executed successfully          |
| `master.transfer_failed`   | Transfer failed            | Master wallet transfer execution failed               |
| `master.signed_success`    | Signing successful         | Master wallet transaction/message signed successfully |
| `master.signed_failed`     | Signing failed             | Master wallet signing operation failed                |

### Payment Link Events

| Event                  | Trigger        | Description                        |
| ---------------------- | -------------- | ---------------------------------- |
| `payment_link.created` | Link generated | New payment link created           |
| `payment_link.updated` | Link updated   | Payment link configuration changed |
| `payment_link.deleted` | Link deleted   | Payment link removed               |

### Payment Link Transfer Events

| Event                           | Trigger            | Description                          |
| ------------------------------- | ------------------ | ------------------------------------ |
| `payment_link_transfer.created` | Transfer initiated | Payment link transfer created        |
| `payment_link_transfer.updated` | Transfer updated   | Payment link transfer status changed |

### Address Settlement Rule Events

| Event                              | Trigger       | Description                                   |
| ---------------------------------- | ------------- | --------------------------------------------- |
| `address_settlement_rule.created`  | Rule created  | Address settlement rule created               |
| `address_settlement_rule.updated`  | Rule updated  | Address settlement rule updated               |
| `address_settlement_rule.deleted`  | Rule deleted  | Address settlement rule removed               |
| `address_settlement_rule.executed` | Rule executed | Address settlement rule executed successfully |
| `address_settlement_rule.failed`   | Rule failed   | Address settlement rule execution failed      |

### Master Settlement Rule Events

| Event                             | Trigger       | Description                                  |
| --------------------------------- | ------------- | -------------------------------------------- |
| `master_settlement_rule.created`  | Rule created  | Master settlement rule created               |
| `master_settlement_rule.updated`  | Rule updated  | Master settlement rule updated               |
| `master_settlement_rule.deleted`  | Rule deleted  | Master settlement rule removed               |
| `master_settlement_rule.executed` | Rule executed | Master settlement rule executed successfully |
| `master_settlement_rule.failed`   | Rule failed   | Master settlement rule execution failed      |

### Wildcard Subscriptions

| Pattern                   | Matches                          |
| ------------------------- | -------------------------------- |
| `address.*`               | All address events               |
| `master.*`                | All master wallet events         |
| `payment_link.*`          | All payment link events          |
| `payment_link_transfer.*` | All payment link transfer events |
| `*`                       | All events                       |

## Webhook Payloads

### Address Incoming Transfer Example

```json theme={null}
{
    "id": "evt_123e4567-e89b-12d3-a456-426614174000",
    "type": "address.incoming_transfer",
    "version": "1.0",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "environment": "prod",
    "data": {
        "hash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "blockNumber": "18500000",
        "from": "0xSenderAddress...",
        "to": "0xRecipientAddress...",
        "value": "100.50",
        "asset": {
            "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "symbol": "EURC",
            "decimals": 6
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base",
            "slug": "base-mainnet"
        },
        "wallet": {
            "id": "addr_123e4567",
            "name": "Customer Deposit Address",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
            "masterWalletId": "master_123e4567"
        },
        "rawContract": {
            "address": "0x08210F9170F89Ab7658F0B5E3fF39b0E03C594D4",
            "decimals": 6,
            "rawValue": "100500000"
        }
    }
}
```

### Master Swap Executed Example

```json theme={null}
{
    "id": "evt_456e7890",
    "type": "master.swap_executed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:35:00.000Z",
    "environment": "prod",
    "data": {
        "status": "SUCCESS",
        "txhash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "explorerUrl": "https://etherscan.io/tx/0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "srcWalet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "dstAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0b5b5",
        "srcAsset": {
            "id": "asset_eth_123",
            "symbol": "ETH",
            "decimals": 18
        },
        "dstAsset": {
            "id": "asset_usdc_456",
            "symbol": "USDC",
            "decimals": 6
        },
        "inputAmount": 1.5,
        "outputAmount": 3450.5,
        "minOutputAmount": 3430.25,
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "gasFee": "0.00021"
    }
}
```

### Payment Link Created Example

```json theme={null}
{
    "id": "evt_789e0123",
    "type": "payment_link.created",
    "version": "1.0",
    "timestamp": "2024-01-15T10:40:00.000Z",
    "environment": "prod",
    "data": {
        "paymentLinkId": "link_123e4567-e89b-12d3-a456-426614174000",
        "name": "Product Purchase",
        "slug": "product-purchase",
        "amount": "100.00",
        "currency": "USD",
        "redirectUrl": "https://yourapp.com/success",
        "isActive": true,
        "expiresAt": null,
        "paymentLimit": null,
        "paymentsConsumed": 0,
        "masterWallet": {
            "id": "master_123e4567",
            "name": "Main Treasury",
            "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        }
    }
}
```

### Settlement Rule Executed Example

```json theme={null}
{
    "id": "evt_234e5678",
    "type": "master_settlement_rule.executed",
    "version": "1.0",
    "timestamp": "2024-01-15T10:45:00.000Z",
    "environment": "prod",
    "data": {
        "ruleId": "rule_123e4567",
        "ruleName": "Auto-Sweep to Treasury",
        "order": "FASTEST",
        "slippageTolerance": "0.5",
        "source": [
            {
                "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
                "minAmount": "10",
                "maxAmount": "1000"
            }
        ],
        "destination": {
            "assetId": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
        },
        "wallet": {
            "id": "master_123e4567",
            "name": "Main Treasury"
        },
        "blockchain": {
            "id": "8a864e95-4b86-423d-9ba4-f4e692ec121e",
            "name": "Base"
        },
        "txhash": "0x28a1bfa727a024dd450352e736f957ac6f08471825362130ef1c3b4da536ebfb",
        "amount": "100.00",
        "asset": {
            "id": "69d851b9-c358-4359-becd-3e614ca1ab4d",
            "symbol": "EURC"
        }
    }
}
```

## Setting Up Webhooks

### Via Dashboard

<Steps>
  <Step title="Navigate to Webhooks">
    Go to **Settings > Webhooks** in the dashboard
  </Step>

  <Step title="Create Webhook">
    Click the **Create Webhook** button
  </Step>

  <Step title="Configure Webhook">
    Fill in the webhook details:

    * **URL**: Your endpoint URL (must be HTTPS)
    * **Name**: A descriptive name
    * **Event Types**: Select the events you want to receive
  </Step>

  <Step title="Copy Secret">
    Copy the generated webhook secret for signature verification
  </Step>

  <Step title="Save and Test">
    Click **Save** and test your webhook with a test event
  </Step>
</Steps>

### Via API

```bash theme={null}
curl -X POST https://api.xentfi.com/v1/webhooks \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/xentfi",
    "name": "Production Webhook",
    "eventTypes": [
      "DEPOSITE_INCOMING_DETECTED",
      "SWAP_EXECUTED",
      "SWAP_FAILED",
      "TRANSFER_EXECUTED",
      "TRANFER_FAILED",
      "SIGNED_SUCCESS",
      "SIGNED_FAILED",
      "DEPOSITE_ADDRESS_CREATED"
    ]
  }'
```

**Response:**

```json theme={null}
{
    "data": {
        "id": "webhook_123e4567-e89b-12d3-a456-426614174000",
        "name": "Production Webhook",
        "description": null,
        "developerId": "dev_123e4567",
        "url": "https://yourapp.com/webhooks/xentfi",
        "eventTypes": [
            "DEPOSITE_INCOMING_DETECTED",
            "SWAP_EXECUTED",
            "SWAP_FAILED",
            "TRANSFER_EXECUTED",
            "TRANFER_FAILED",
            "SIGNED_SUCCESS",
            "SIGNED_FAILED",
            "DEPOSITE_ADDRESS_CREATED"
        ],
        "secret": "whsec_abc123def456ghi789jkl...",
        "isActive": true,
        "createdAt": "2024-01-15T10:30:00.000Z",
        "updatedAt": "2024-01-15T10:30:00.000Z"
    }
}
```

## Managing Webhooks

### List Webhooks

```bash theme={null}
curl -X GET https://api.xentfi.com/v1/webhooks \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -G \
  -d "limit=10" \
  -d "offset=0" \
  -d "isActive=true"
```

### Get Webhook Details

```bash theme={null}
curl -X GET https://api.xentfi.com/v1/webhooks/{subscriptionId} \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id"
```

### Update Webhook

```bash theme={null}
curl -X PUT https://api.xentfi.com/v1/webhooks/{subscriptionId} \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/new-endpoint",
    "isActive": true,
    "eventTypes": [
      "DEPOSITE_INCOMING_DETECTED",
      "SWAP_EXECUTED"
    ]
  }'
```

### Rotate Webhook Secret

```bash theme={null}
curl -X POST https://api.xentfi.com/v1/webhooks/{subscriptionId}/secret/rotate \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id"
```

## Signature Verification

### Why Verify Signatures?

Webhook signatures ensure that requests truly come from XentFi and not an imposter.

### Verification Code Example

```javascript theme={null}
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
```

## Retry Logic

### Retry Schedule

| Attempt | Delay      | Total Wait            |
| ------- | ---------- | --------------------- |
| 1       | Immediate  | 0 seconds             |
| 2       | 5 seconds  | 5 seconds             |
| 3       | 30 seconds | 35 seconds            |
| 4       | 5 minutes  | 5 minutes 35 seconds  |
| 5       | 30 minutes | 35 minutes 35 seconds |
| 6       | 1 hour     | 1 hour 35 minutes     |
| 7       | 2 hours    | 3 hours 35 minutes    |
| 8       | 6 hours    | 9 hours 35 minutes    |

### Webhook Events & Retries

You can monitor webhook event delivery status:

```bash theme={null}
curl -X GET https://api.xentfi.com/v1/webhook-events \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id" \
  -G \
  -d "subscriptionId=webhook_123e4567" \
  -d "limit=10" \
  -d "status=FAILED"
```

**Response:**

```json theme={null}
{
    "data": [
        {
            "id": "event_123e4567-e89b-12d3-a456-426614174000",
            "type": "DEPOSITE_INCOMING_DETECTED",
            "payload": { ... },
            "status": "FAILED",
            "responseStatusCode": 500,
            "errorMessage": "Connection timeout",
            "retryCount": 3,
            "createdAt": "2024-01-15T10:30:00.000Z",
            "updatedAt": "2024-01-15T10:35:00.000Z"
        }
    ],
    "total": 1,
    "hasMore": false
}
```

### Get Webhook Event Details

```bash theme={null}
curl -X GET https://api.xentfi.com/v1/webhook-events/{eventId} \
  -H "apiKey: your-api-key" \
  -H "orgId: your-org-id"
```

## Best Practices

<Info>
  * **Always verify signatures** - Never trust unverified webhooks
  * **Respond quickly** - Return 2xx within 5 seconds
  * **Idempotent processing** - Handle duplicate webhooks gracefully
  * **Log all webhooks** - Keep audit trail for debugging
  * **Monitor failures** - Set up alerts for failed deliveries
  * **Queue processing** - Use message queues for async handling
  * **Keep endpoints public** - Must be accessible from the internet
</Info>

## Webhook Headers

| Header   | Description                     | Example                 |
| -------- | ------------------------------- | ----------------------- |
| `apiKey` | Your API key for authentication | `xentfi_live_abc123...` |
| `orgId`  | Your organization ID            | `org_123e4567`          |

## Event Delivery Status

| Status    | Description                           |
| --------- | ------------------------------------- |
| `PENDING` | Event queued for delivery             |
| `SUCCESS` | Delivered successfully (2xx response) |
| `FAILED`  | Delivery failed (non-2xx response)    |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook not received">
    **Possible causes:**

    * Endpoint not publicly accessible
    * Firewall blocking requests
    * Invalid URL format
    * Webhook not active

    **Solutions:**

    * Verify URL is accessible from internet
    * Check firewall rules
    * Ensure URL includes https\://
    * Verify webhook is active in dashboard
  </Accordion>

  <Accordion title="Signature verification fails">
    **Possible causes:**

    * Wrong secret used
    * Payload body modified
    * Encoding issues

    **Solutions:**

    * Rotate and update secret
    * Use raw request body
    * Verify JSON stringification
  </Accordion>

  <Accordion title="Duplicate webhooks received">
    **Solutions:**

    * Implement idempotency using webhook ID
    * Check for processed flag in your database
    * Use unique constraint on webhook ID
  </Accordion>

  <Accordion title="High latency responses">
    **Solutions:**

    * Process webhooks asynchronously
    * Use message queue (RabbitMQ, SQS)
    * Return 202 Accepted for long processing
  </Accordion>
</AccordionGroup>

## API Reference

| Endpoint                                      | Method | Description                 |
| --------------------------------------------- | ------ | --------------------------- |
| `/v1/webhooks`                                | GET    | List webhook subscriptions  |
| `/v1/webhooks`                                | POST   | Create webhook subscription |
| `/v1/webhooks/{subscriptionId}`               | GET    | Get webhook details         |
| `/v1/webhooks/{subscriptionId}`               | PUT    | Update webhook              |
| `/v1/webhooks/{subscriptionId}/secret/rotate` | POST   | Rotate webhook secret       |
| `/v1/webhook-events`                          | GET    | List webhook events         |
| `/v1/webhook-events/{eventId}`                | GET    | Get webhook event details   |

## Related Products

<CardGroup cols={3}>
  <Card title="Payment Links" icon="link" href="/products/payment-links">
    Payment event notifications
  </Card>

  <Card title="Auto Settlement" icon="automation" href="/products/auto-settlement">
    Settlement event notifications
  </Card>

  <Card title="Master Wallets" icon="wallet" href="/products/master-wallets">
    Wallet event notifications
  </Card>
</CardGroup>

## Next Steps

* [Set up your webhook endpoint](/api-reference) in API Reference
* [Register your webhook](/api-reference) with XentFi
* [Monitor webhook deliveries](/api-reference) in dashboard