# Custom Integration Setup (Webhook)

Our Custom Integration option provides a flexible way to send event data from our platform directly to your own systems or third-party services via webhooks. This is a self-serve integration where you configure an endpoint URL to receive event notifications.

## How it Works

When a relevant event occurs within our platform (based on your configuration or system triggers), we will send an HTTP POST request containing the event data (in JSON format) to the **Endpoint URL** you specify.

To allow your endpoint to verify that the request genuinely originated from our platform, we include a unique **Integration Key** in the request headers.

## Setup Process

1. **Create Integration in Our Portal:**
  * Log in to your account on our platform.
  * Navigate to the **Configuration -> Integrations** page.
  * Click to create a new custom integration.
  * Give your integration a descriptive name (e.g., "Send Orders to My CRM").
  * Enter the **Endpoint URL**: This is the public URL of *your* application or service that is ready to receive HTTP POST requests with JSON payloads.
  * Save the integration configuration.
2. **Obtain Your Integration Key:**
  * Once the integration is saved, a unique **Integration Key** will be generated and displayed.
  * **Copy this key securely.** You will need it to validate incoming requests on your endpoint.
3. **Configure Your Endpoint:**
  * Ensure your **Endpoint URL** is accessible from the public internet.
  * Implement logic at your endpoint to:
    * Receive HTTP POST requests.
    * Parse the JSON body containing the event data.
    * **Validate the request:** Check for the presence of the `x-helix-key` header in the incoming request. The value of this header **must match** the **Integration Key** you obtained in Step 2. Reject or flag requests that do not have a valid key.
    * Process the event data as needed by your system.


## Validating Incoming Events

For security, your endpoint *must* validate incoming webhook requests to ensure they originated from our platform.

* **Check Header:** Look for the HTTP header `x-helix-key`.
* **Compare Value:** Compare the value of the `x-helix-key` header against the **Integration Key** associated with this specific custom integration in our portal.
* **Action:** If the header is missing or the value does not match, you should treat the request as invalid and potentially discard it.



```http
POST /your-webhook-endpoint HTTP/1.1
Host: yourdomain.com
Content-Type: application/json
x-helix-key: YOUR_UNIQUE_INTEGRATION_KEY_HERE

{
  "event_id": "evt.",
  "event_type": "event.test",
  "timestamp": "2023-10-27T10:30:00Z",
  "data": {
    "id": "123",
    "details": "..."
    // ... other event data
  }
}
```

## Further Reading

- **Events** [Event Reference](/guides/integrations.custom-events)