Webhooks

Our Webhooks API lets your application receive real-time updates whenever customers, transactions, or counterparties change in Conduit. You can register an HTTPS endpoint, and Conduit will deliver event notifications to it automatically. This means your application stays updated without constant polling.

Key Concepts

A webhook is a URL that Conduit will call when certain events occur. For example, when a transaction is created, Conduit will call the webhook URL with the transaction details.

Events

An event is a specific action that can occur in Conduit. For example, a transaction can be created, updated, or deleted.

Ways to configure Webhooks

We offer two ways to configure and manage webhooks on your account

Via the conduit Dashboard

Login into your Conduit Dashboard
Click Webhooks in the navigation menu to view, create, or manage endpoints.

You need to have developer permissions to see this section on the dashboard. Reach out to your account manager for access if you don’t.

Via the Webhooks API

Use our Webhooks API to programmatically create, update, list, or delete webhook endpoints.
See the API Reference for request and response examples.

Your webhook endpoint must accept JSON payloads and respond with a 200 OK status quickly to prevent retries and timeouts. Conduit will retry delivery up to 10 times over 24 hours before marking the event as failed.

Supported Webhook Events

Conduit supports the following webhook event notifications, grouped by resource type.

Counterparty Events

These events notify you of changes in a counterparty’s lifecycle from activation to compliance checks.

Event Name	Description
`counterparty.active`	Counterparty becomes active
`counterparty.compliance_rejected`	Counterparty fails compliance review
`counterparty.deleted`	Counterparty is deleted
`counterparty.in_compliance_review`	Counterparty enters compliance review

Counterparty Statuses

The counterparty object within the payload will have one of the following statuses:

Status	Description
`active`	Counterparty is active and approved for transactions.
`in_compliance_review`	Counterparty is currently undergoing compliance checks.
`compliance_rejected`	Counterparty has failed compliance checks.
`deleted`	Counterparty has been deleted or disabled.

Customer Events

These events track important customer status updates — including onboarding progress, compliance checks, and KYB status.

Event Name	Description
`customer.active`	Customer becomes active
`customer.in_compliance_review`	Customer enters compliance review
`customer.compliance_rejected`	Customer fails compliance review
`customer.created`	Customer is created
`customer.kyb_in_progress`	Customer KYB verification in progress
`customer.kyb_expired`	Customer KYB verification expired
`customer.kyb_missing_information`	Customer KYB verification missing information
`customer.account_onboarding_pending`	Customer onboarding pending

Transaction Events

These events cover the full transaction lifecycle — from creation to settlement — including compliance decisions and payment processing.

Event Name	Description
`transaction.created`	New transaction
`transaction.compliance_approved`	Transaction approved in compliance
`transaction.compliance_rejected`	Transaction rejected in compliance
`transaction.completed`	Transaction completed
`transaction.awaiting_funds`	Transaction awaiting funds
`transaction.funds_received`	Transaction funds received
`transaction.cancelled`	Transaction cancelled
`transaction.in_compliance_review`	Transaction under compliance review
`transaction.awaiting_compliance_review`	Transaction awaiting compliance review
`transaction.processing_withdrawal`	Processing a withdrawal
`transaction.withdrawal_processed`	Withdrawal processed
`transaction.processing_settlement`	Processing settlement
`transaction.settlement_processed`	Settlement processed
`transaction.processing_payment`	Processing payment
`transaction.payment_processed`	Payment processed

Transaction Statuses

The transaction object within the payload will have one of the following statuses, reflecting its current state in the lifecycle:

Status	Description
`initializing`	Transaction is being initialized.
`created`	Transaction has been successfully created.
`compliance_approved`	Transaction has passed compliance checks.
`compliance_rejected`	Transaction has failed compliance checks.
`completed`	Transaction has been completed.
`awaiting_funds`	Waiting for funds to be received (e.g., for an Offramp).
`funds_received`	Funds have been received.
`cancelled`	Transaction has been cancelled.
`in_compliance_review`	Transaction is currently under compliance review.
`awaiting_compliance_review`	Transaction is queued for compliance review.
`processing_withdrawal`	Withdrawal is currently being processed.
`withdrawal_processed`	Withdrawal has been successfully processed.
`processing_settlement`	Settlement is currently being processed.
`settlement_processed`	Settlement has been successfully processed.
`processing_payment`	Payment to the destination is being processed.
`payment_processed`	Payment to the destination has been processed.

Understanding Webhook Payloads

Webhook event payloads contain the full resource object (transaction, customer, or counterparty) at the time of the event. The structure and data types of these objects match exactly what you would receive from the corresponding API endpoints.

Payload Structure

Each webhook payload follows this structure:

{
  "event": "transaction.created",
  "version": "1.0",
  "event_timestamp": 1732280510579,
  "event_sequence": 12345,
  "data": {
    "transaction": {
      // Full transaction object
    }
  }
}

Field	Type	Description
`event`	string	The event type (e.g., `transaction.created`)
`version`	string	The payload version
`event_timestamp`	number	Unix timestamp in milliseconds when the event occurred
`event_sequence`	number	Optional. Sequence number for ordering events from the same stream
`data`	object	Contains the full resource object

Using event_timestamp and event_sequence:

Use event_timestamp to determine when an event occurred and to detect stale events
Use event_sequence (when present) to detect out-of-order delivery and ensure correct processing order
Events with a higher sequence number occurred after events with a lower sequence number within the same event stream

Understanding Data Types and Fields

The data types, field names, and structure within the webhook payload are identical to what the corresponding API endpoint returns. This ensures consistency across our API and webhooks. For detailed field documentation:

Transaction webhooks → See Get Transaction API Reference
Customer webhooks → See Get Customer API Reference
Counterparty webhooks → See Get Counterparty API Reference

Example: Counterparty Webhook Payload

When a counterparty.active event occurs, the webhook payload contains the full counterparty object.

{
  "event": "counterparty.active",
  "version": "1.0",
  "event_timestamp": 1732189800000,
  "event_sequence": 48291,
  "data": {
    "counterparty": {
      "id": "cp_2y5qudOSwzlDrbuSWc4oazlJ0Ef",
      "type": "business",
      "businessName": "Acme Suppliers Ltd",
      "customerId": "cus_35nFQH8i29iaNIrOxBBfXnMeKRq",
      "email": "payments@acme-suppliers.com",
      "phone": "+12125551234",
      "website": "https://acme-suppliers.com",
      "identificationType": "EIN",
      "identificationNumber": "12-3456789",
      "address": {
        "streetLine1": "123 Supply Chain Rd",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "country": "USA"
      },
      "paymentMethods": [
        {
          "id": "bank_2y5qudOSwzlDrbuSWc4oazlJ0Ef",
          "type": "bank",
          "accountNumber": "987654321",
          "routingNumber": "123456789",
          "bankName": "Chase Bank",
          "currency": "USD"
        }
      ],
      "documents": [],
      "status": "active",
      "messages": [],
      "createdAt": "2025-11-20T10:00:00.000Z",
      "updatedAt": "2025-11-21T11:30:00.000Z"
    }
  }
}

Example: Transaction Webhook Payload

When a transaction.awaiting_compliance_review event occurs, the webhook payload contains the full transaction object. Below are examples for different transaction types.

1. Offramp Transaction

{
  "event": "transaction.awaiting_compliance_review",
  "version": "1.0",
  "event_timestamp": 1732199510579,
  "event_sequence": 52103,
  "data": {
    "transaction": {
      "type": "offramp",
      "id": "trxn_35nFQH8i29iaNIrOxBBfXnMeKRq",
      "quoteId": "quote_35nFMW6JEC2xtQfn0ustyqiuZnN",
      "status": "AWAITING_COMPLIANCE_REVIEW",
      "source": {
        "id": "bank_34nhPpxlSduJlt8tNlCsIuwGUPq",
        "assetCountry": "USA",
        "amount": {
           "asset": "USDT",
           "network": "ethereum",
           "value": "10.000000"
        }
      },
      "destination": {
        "id": "bank_2y5qudOSwzlDrbuSWc4oazlJ0Ef",
        "assetCountry": "BRA",
        "amount": {
           "asset": "BRL",
           "value": "53.58"
        }
      },
      "documents": [
        {
          "id": "doc_35nFQ6z9ApMGsrfzhj8pHt0hvOq"
        },
        {
          "id": "doc_2xNMCi5TsLaOIvy9fp6zFbRCh9z"
        }
      ],
      "purpose": "12823-TradeOfGoods",
      "reference": null,
      "createdAt": "2025-11-21T15:11:50.579Z",
      "clientId": "client_2HhdamxMUpQfb1lk5lsUdnIdv4H"
    }
  }
}

4. Conversion Transaction

{
  "event": "transaction.processing_settlement",
  "version": "1.0",
  "data": {
    "transaction": {
      "id": "trxn_38jHo9KDvQPBtOotdKyIWeiqYZ0",
      "type": "conversion",
      "source": {
        "id": "acct_3ypmRBqEMD7E4HFEqv5qHFO8BET",
        "amount": {
          "amount": "7500000",
          "decimals": 6,
          "assetType": "EURC",
          "assetTypeNetwork": {
            "assetType": "EURC",
            "networkId": "ethereum:ropsten"
          },
          "standardDecimals": 6
        },
        "assetCountry": "FRA"
      },
      "status": "PROCESSING_SETTLEMENT",
      "quoteId": "quote_30yHnKfSbz0VvgjuMqE7LKNUGrZ",
      "clientId": "client_3xpmRChD8Gx51ZfduSBxdN5rJhw",
      "createdAt": "2025-09-15T12:57:43.161Z",
      "completedAt": null,
      "destination": {
        "id": "acct_4ypmRBqEMW7E4BFEqv5qHFO8BEP",
        "amount": {
          "amount": "7482701",
          "decimals": 6,
          "assetType": "BTCT",
          "assetTypeNetwork": {
            "assetType": "BTCT",
            "networkId": "bitcoin:testnet"
          },
          "standardDecimals": 6
        },
        "assetCountry": "DEU"
      }
    }
  }
}

2. Onramp Transaction

Onramp transactions include an onRampInstructions field containing details for the deposit.

{
  "event": "transaction.created",
  "version": "1.0",
  "data": {
    "transaction": {
      "type": "onramp",
      "id": "trxn_47mGQH9j38kbOJsPyCCgYnNeLSt",
      "quoteId": "quote_47mGNX7KFD3yuRgm1vtsxrjuAoP",
      "status": "CREATED",
      "source": {
        "id": "bank_56oiQqymTeuKms9uOmDtJvwHVQr",
        "assetCountry": "BRA",
        "amount": {
            "asset": "BRL",
            "value": "100.00"
        }
      },
      "destination": {
        "id": "wlt_3z6rvcPSxcmErbuTxd5pbzlK1Fg",
        "amount": {
            "asset": "USDC",
            "network": "ethereum",
            "value": "18.500000"
        }
      },
      "onRampInstructions": {
        "status": "ready",
        "data": [
          {
            "accountNumber": "123456789",
            "routingNumber": "987654321",
            "bankName": "Partner Bank",
            "beneficiaryName": "Conduit Financial",
            "reference": "REF-12345"
          }
        ]
      },
      "purpose": "Investment",
      "reference": "MyOnrampRef",
      "createdAt": "2025-11-22T10:05:30.123Z",
      "clientId": "client_2HhdamxMUpQfb1lk5lsUdnIdv4H"
    }
  }
}

3. Withdrawal Transaction

Withdrawal transactions include a blockchainTxHash once processed on-chain.

{
  "event": "transaction.created",
  "version": "1.0",
  "data": {
    "transaction": {
      "id": "trxn_54FD7qOMC5Qx4inZ4UYvEjk2m9D",
      "type": "onramp",
      "source": {
        "id": "bank_4z2Z9r1DccYi1990nmQ9yO3fYVH",
        "amount": {
          "amount": "150000000",
          "decimals": 2,
          "assetType": "USD",
          "assetTypeNetwork": {
            "assetType": "USD",
            "networkId": "fiat"
          },
          "standardDecimals": 2
        },
        "assetCountry": "CAN"
      },
      "status": "CREATED",
      "purpose": "36025-Healthcare",
      "quoteId": "quote_54TTrefwnYJHuapjUvxQynWHhAp",
      "clientId": "client_4yqnSDiF0Ky62ZiduUDyfO7sJkz",
      "createdAt": "2025-11-20T10:45:36.754Z",
      "documents": [
        {
          "id": "doc_54FD5Y9Tli8g7Jpb8QYal9bJ7Y"
        },
        {
          "id": "doc_54FD6khPFspVYxZKpGyzX8j8j5u"
        }
      ],
      "reference": "Ref-OnRamp-78901",
      "completedAt": null,
      "destination": {
        "id": "wlt_54UVyeHGqCLPfKb2zH8QVjgDH9Y",
        "amount": {
          "amount": "27345670",
          "decimals": 6,
          "assetType": "BTC",
          "assetTypeNetwork": {
            "assetType": "BTC",
            "networkId": "bitcoin:mainnet"
          },
          "standardDecimals": 8
        },
        "assetCountry": "MEX"
      },
      "onRampInstructions": {
        "data": [
          {
            "key": "5ce758fe-8998-5gf7-10g5-7fbeg43554cd",
            "rail": "npc",
            "asset": "USD",
            "qrCodeImageBase64": "newBase64EncodedQRCode"
          },
          {
            "bank": {
              "bankName": "Royal Bank (241)",
              "branchCode": "0034",
              "accountNumber": "007530410-5"
            },
            "rail": "wire",
            "asset": "USD",
            "accountOwner": {
              "name": "CONDUIT SOLUTIONS LTD",
              "identificationType": "BN",
              "identificationNumber": "987654321"
            }
          }
        ],
        "status": "pending"
      }
    }
  }
}

7. New Onramp Transaction

{
  "event": "transaction.funds_received",
  "data": {
    "transaction": {
      "id": "trxn_43TP8qXME5Kz3hpX3XXiFJb2k9C",
      "type": "onramp",
      "source": {
        "id": "bank_3z1Y9g1DbcZh1989mlP8xN2eWUG",
        "amount": {
          "amount": "200000000",
          "decimals": 4,
          "assetType": "GBP",
          "assetTypeNetwork": {
            "assetType": "GBP",
            "networkId": "fiat"
          },
          "standardDecimals": 2
        },
        "assetCountry": "GBR"
      },
      "status": "FUNDS_RECEIVED",
      "purpose": "56021-RealEstate",
      "quoteId": "quote_43TOzgvmxVYHuaPiTszOxnYHfAp",
      "clientId": "client_3ypnRCiE9Jx61ZgduTCxeN6rJjy",
      "createdAt": "2025-10-15T11:25:47.321Z",
      "documents": [
        {
          "id": "doc_43TP4Y9Slh7f6Jpa7PYZk8aH6X"
        },
        {
          "id": "doc_43TP5jhOEspUXwZJoFyzW7i7h4r"
        }
      ],
      "reference": "Ref-OnRamp-67890",
      "completedAt": null,
      "destination": {
        "id": "wlt_43SUxdFGrBKOfJa1zH7PWifCG8X",
        "amount": {
          "amount": "36574670",
          "decimals": 6,
          "assetType": "ETH",
          "assetTypeNetwork": {
            "assetType": "ETH",
            "networkId": "ethereum:mainnet"
          },
          "standardDecimals": 18
        },
        "assetCountry": "USA"
      },
      "onRampInstructions": {
        "data": [
          {
            "key": "4bd647ed-7887-4ff5-99f5-6eadf32443bc",
            "rail": "swift",
            "asset": "GBP",
            "qrCodeImageBase64": "randomBase64EncodedQRCode"
          },
          {
            "bank": {
              "bankName": "Barclays Bank (172)",
              "branchCode": "0012",
              "accountNumber": "006420399-2"
            },
            "rail": "chaps",
            "asset": "GBP",
            "accountOwner": {
              "name": "CONDUIT TECHNOLOGY LTD",
              "identificationType": "CRN",
              "identificationNumber": "12345678"
            }
          }
        ],
        "status": "ready"
      }
    }
  }
}

5. Deposit Transaction

Crypto deposit transactions include a blockchainTxHash once the transaction is confirmed on-chain.

{
  "event": "transaction.compliance_approved",
  "version": "1.0",
  "data": {
    "transaction": {
      "id": "trxn_41AYopyt1Zc47AxEiHSbYkf7dU2",
      "type": "deposit",
      "blockchainTxHash": "0xdcc3e84b0b1f28be620b9efa0b2efe8758eeaa749eee564c4901a56b549ba8b4",
      "source": {
        "amount": {
          "amount": "50000000",
          "decimals": 6,
          "assetType": "ETH",
          "assetTypeNetwork": {
            "assetType": "ETH",
            "networkId": "ethereum:rinkeby"
          },
          "standardDecimals": 18
        },
        "address": "0x1111111111111111111111111111111111111111"
      },
      "status": "COMPLIANCE_APPROVED",
      "purpose": "Investment",
      "clientId": "client_3ypmRChD7Hx51ZfduSBxdN5rJhK",
      "createdAt": "2025-09-25T10:30:45.789Z",
      "reference": "Ref-Deposit-12345",
      "completedAt": null,
      "destination": {
        "id": "acct_3xpmRBqEMD7E4BFEqv5qHFO8BEP",
        "amount": {
          "amount": "50000000",
          "decimals": 6,
          "assetType": "ETH",
          "assetTypeNetwork": {
            "assetType": "ETH",
            "networkId": "ethereum:rinkeby"
          },
          "standardDecimals": 18
        }
      }
    }
  }
}

The transaction object in the webhook payload has the exact same structure, field names, and data types as the response from the Get Transaction API endpoint. Refer to that API reference for complete field documentation.

Best Practices

The following are the list of best practices that you need to have in place to for a smooth integration with our webhook.

1. Handle Idempotency with `conduit-webhook-idempotency-key`

Every webhook request from Conduit includes a unique conduit-webhook-idempotency-key header.
Use this key to ensure that the same event is not processed more than once. Recommended approach:

Read the header value from the request.
Check if this key was already processed in your system.
Skip processing if the key is found (to prevent duplicate effects).
Store keys temporarily in a database or cache (e.g., Redis)
Clean up old keys periodically.

Why it’s important:
Webhook retries can occur due to network issues or failed acknowledgements.
Idempotency ensures that your system processes each event only once, preserving data integrity.

2. Verify Webhook Signatures

Always validate webhook signatures to ensure:

The request truly originated from Conduit.
The payload has not been altered in transit.

Additional security measures:

Replay attack prevention – validate the timestamp in the webhook header conduit-signature-timestamp and reject requests that are too old (e.g., older than 5 minutes).
Constant-time comparison – compare the expected and actual signatures in constant time to prevent timing attacks.

3. Respond Quickly

Return a 200 OK status as soon as possible. If processing takes a long time, consider deferring it to a background job.

IP Address Whitelisting

For an additional layer of security, you can restrict incoming webhook requests to only those originating from Conduit’s official IP addresses. This ensures that only Conduit can trigger your webhook endpoint, reducing the risk of unauthorized requests. Why Whitelist IPs?
• Prevents webhook spoofing from unknown sources.
• Adds an extra security layer alongside signature verification.
• Useful for organizations with strict network access controls.

Environment	IP Address
Sandbox	3.97.46.187/32
Live	3.98.205.40/32

What’s next?

Learn how to create your first webhook by following our Configuring Your First Webhook guide.
For more on the Webhooks API information please check the API Reference Section

Getting started

Guides

Developer Tools

Webhooks

Key Concepts

Webhooks

Events

Ways to configure Webhooks

Via the conduit Dashboard

Via the Webhooks API

Supported Webhook Events

Counterparty Events

Counterparty Statuses

Customer Events

Transaction Events

Transaction Statuses

Understanding Webhook Payloads

Payload Structure

Understanding Data Types and Fields

Example: Counterparty Webhook Payload

Example: Transaction Webhook Payload

1. Offramp Transaction

4. Conversion Transaction

2. Onramp Transaction

3. Withdrawal Transaction

7. New Onramp Transaction

5. Deposit Transaction

Best Practices

1. Handle Idempotency with `conduit-webhook-idempotency-key`

2. Verify Webhook Signatures

3. Respond Quickly

IP Address Whitelisting

What’s next?

​Key Concepts

​Webhooks

​Events

​Ways to configure Webhooks

​Via the conduit Dashboard

​Via the Webhooks API

​Supported Webhook Events

​Counterparty Events

​Counterparty Statuses

​Customer Events

​Transaction Events

​Transaction Statuses

​Understanding Webhook Payloads

​Payload Structure

​Understanding Data Types and Fields

​Example: Counterparty Webhook Payload

​Example: Transaction Webhook Payload

​1. Offramp Transaction

​4. Conversion Transaction

​2. Onramp Transaction

​3. Withdrawal Transaction

​7. New Onramp Transaction

​5. Deposit Transaction

​Best Practices

​1. Handle Idempotency with conduit-webhook-idempotency-key

​2. Verify Webhook Signatures

​3. Respond Quickly

​IP Address Whitelisting

​What’s next?

Key Concepts

Webhooks

Events

Ways to configure Webhooks

Via the conduit Dashboard

Via the Webhooks API

Supported Webhook Events

Counterparty Events

Counterparty Statuses

Customer Events

Transaction Events

Transaction Statuses

Understanding Webhook Payloads

Payload Structure

Understanding Data Types and Fields

Example: Counterparty Webhook Payload

Example: Transaction Webhook Payload

1. Offramp Transaction

4. Conversion Transaction

2. Onramp Transaction

3. Withdrawal Transaction

7. New Onramp Transaction

5. Deposit Transaction

Best Practices

1. Handle Idempotency with `conduit-webhook-idempotency-key`

2. Verify Webhook Signatures

3. Respond Quickly

IP Address Whitelisting

What’s next?