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.
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.
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.
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.
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-keyheader 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.
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-keyheader 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.
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
}
}- Events Event Reference