> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conduit.financial/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
> Get real-time updates when certain events occur in Conduit
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
### Webhooks
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](/api-reference/webhooks/create-a-webhook) 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:
```json theme={null}
{
"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](/api-reference/transactions/get-transaction)
* **Customer webhooks** → See [Get Customer API Reference](/api-reference/customers/get-customer)
* **Counterparty webhooks** → See [Get Counterparty API Reference](/api-reference/counterparties/get-counterparty)
### Example: Counterparty Webhook Payload
When a `counterparty.active` event occurs, the webhook payload contains the full counterparty object.
```json theme={null}
{
"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
```json theme={null}
{
"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
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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
```json theme={null}
{
"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.
```json theme={null}
{
"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](/api-reference/transactions/get-transaction). 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](/guides/webhooks/first-webhook) guide.
* For more on the Webhooks API information please check the [API Reference](/api-reference/webhooks/create-webhook) Section