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

​

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.

​

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.

​

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

​

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

​

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