> ## 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. # Configuring Webhooks > This guide shows how to create your first webhook on Conduit using the Webhook API on Conduit. ## Pre-requisites * You have an active Conduit account with API access * You have API credentials (API Key and Secret) * You have understood our [Webhooks](/developer-sections/webhooks) Developer Section In this guide, we will learn how to create your first webhook. 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. ### Registering Webhook Endpoint To start receiving real-time updates, you must register your webhook endpoint with Conduit. You can do this by sending a POST request to the /webhooks API endpoint with your webhook details. ### Request Example ```bash theme={null} curl -X POST https://api.conduit.financial/webhooks \ -H "X-API-Key: your_api_key" \ -H "X-API-Secret: your_api_secret" \ -H "Content-Type: application/json" \ -d '{ "url": "your_webhook_url", "status": "enabled", "events": ["your_subscribed_event"], "organizationId": "your_client_id" }' ``` **Request Parameters**: | Parameter | Type | Description | | :------------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | | url | string | Your webhook endpoint URL to receive events | | status | string | Status of the webhook, typically "enabled" when creating | | events | Array | Array of event types you want to subscribe to (refer to [events ](/developer-sections/webhooks#supported-webhook-events) section on the supported events) | | organizationId | string | Your client or organization identifier | **Example Response** ```json theme={null} { "id": "whk_31BbTJ0ORWosbmona9WP0ThJYT5", "url": "https://www.example.com/webhooks", "status": "enabled", "organizationId": "client_2zsj24vsMLU9emYzu2rZXlJhQs", "events": [ "counterparty.active" ] } ``` \*\* Response Field description\*\* | Field | Description | | | :------------- | :---------------------------------------------------------------------------------------------------------------- | :- | | id | The unique identifier of the webhook entry | | | url | Your webhook endpoint URL to receive events | | | events | Array of event types you subscribed to (refer to [events](/developer-sections/webhooks#supported-webhook-events)) | | | organizationId | Your client or organization identifier | | | status | Status of the webhook, "enabled" | | ### Retrieve Your Webhook Secret Before you can verify incoming webhook requests, you need the secret associated with your webhook. This secret is used to validate the authenticity of each request from Conduit, protecting your system from unauthorized or forged events. To find your webhook secret: 1. Log into your Conduit Dashboard 2. Navigate to the **Webhooks** tab. 3. Locate the webhook you created and click on it 4. Click on it to view the **Key Secret** field this what you use in your signature verification process. ### Verifying Webhook Requests For security,\*\* every webhook request from Conduit must be verified before processing\*\*. Use the secret you retrieved above to validate the HMAC SHA-256 signature included in each request header. The following NodeJS handler middleware demonstrates how to implement a secure webhook receiver that: * Extracts the signature headers from the incoming request. * Recreates the HMAC signature using your webhook secret for verification. ```javascript theme={null} const express = require('express'); const crypto = require('crypto'); const app = express(); // Middleware to parse JSON bodies app.use(express.json()); // Middleware to validate incoming webhook requests const validateWebhook = (req, res, next) => { // Extract signature and timestamp headers from the request const signature = req.headers['conduit-signature']; const timestamp = req.headers['conduit-signature-timestamp']; // Reject request if headers are missing if (!signature || !timestamp) { console.error('Missing signature headers'); return res.status(401).send({ error: 'Missing signature headers' }); } // Get your webhook secret from environment variables const secret = process.env.WEBHOOK_SECRET; if (!secret) { console.error('Webhook secret is not configured'); return res.status(500).send({ error: 'Server configuration error' }); } // Convert request body to string for signing const payload = JSON.stringify(req.body); // Create the string to sign: "." const stringToSign = `${timestamp}.${payload}`; try { // Compute HMAC SHA256 hash using your secret const expectedSignature = crypto .createHmac('sha256', secret) .update(stringToSign) .digest('hex'); // Compare expected signature with the one sent by Conduit if (expectedSignature !== signature) { console.error('Invalid signature'); return res.status(401).send({ error: 'Invalid signature' }); } // Signature verified — proceed to next middleware or route handler next(); } catch (error) { console.error('Webhook validation error:', error); return res.status(401).send({ error: 'Webhook validation failed' }); } }; // Webhook endpoint with validation middleware applied app.post('/', validateWebhook, (req, res) => { res.status(200).send({ message: 'Webhook received' }); }); // Start server const PORT = process.env.PORT || 9876; app.listen(PORT, () => { console.log(`Webhook client listening on port ${PORT}`); }); ``` ### Structure of Webhook Payload Each webhook you receive from Conduit follows a consistent structure. ```json theme={null} { "event": "WebhookEventType", "version": "1.0", "data": { // object with the data } } } ``` **Field descriptions**: | Field | Type | Description | | :------ | :----- | :--------------------------------------------------------------------------------- | | event | string | The type of event that occurred, e.g., counterparty.active, customer.created. | | version | string | The webhook payload version. Use this to ensure compatibility with future updates. | | data | object | Contains the main event data, this can counterparty, transaction or customer. | | | | | ### Payload Examples For a comprehensive list of webhook events and detailed payload examples for all resource types (including Transactions, Customers, and Counterparties), please refer to our **[Webhooks Reference](/developer-sections/webhooks#supported-webhook-events)**. For list of all the events that you can subscribe to, please check our [Webhooks Supported Events](/developer-sections/webhooks#supported-webhook-events) Developer Section. ## What's next? * Review supported events: [Webhooks Supported Events](/developer-sections/webhooks#supported-webhook-events) ## Support Reach out to our [support team](https://support.conduitpay.com/) to get help and share your feedback.