HTTP Event API Source

Background

We have dedicated connectors for Website, Mobile and popular backend systems using Java, Python, Node.JS.

They are built with high-performance and asynchronous best-practices.

However, if your system is not included in the above list, you still can send your events to Filum using direct HTTP Request. This guideline will help you to do just that.

Requirements

• Edit permission to your backend source code.
• Knowledge to configure and send HTTP Request in your programming language of choice.

Use Cases

• Track events from projects that is NOT natively supported by Filum (as of now PHP and .NET are examples)

Guideline

Headers

Content-Type

To send your event data to our Event API using HTTP Request, please set the content-type of the header to application/json

Authentication

For authentication, let's configure your authentication as followed, be aware of a space after Bearer:

'Authorization': 'Bearer ' + YOUR_WRITEKEY

Example:

'Authorization': 'Bearer ' + "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOjM0OH0.eTKQX4vcKFkx2jQs7S1GzDwbbc2cxdaqcQr2Ydhgafw"

Response

Our Event API endpoint will response with the code 200 for a correct request, your event then can be viewed in the Debugging tab of your source.

If there is any error in the request, we will return an error response containing:

• The error messages
• The status code

Please check the error messages to find the reason, fix it and retry again.

Usage

To send event data to Filum Event API, you need to know the Endpoint and the specification of the payload.

• Event API Endpoint for both Identify and Track call:

  https://event.filum.ai/events

• The specification of the payload is as followed:

Property	Type	Required	Description
event_type	String	Required	identify for Identify call and track for Track call
event_name	String	Required	- Identify for Identify call and a meaningful name for Track call (Eg: Order Completed, Transaction Failed or eKYC Result Returned etc.)
context	Object	Optional	Contains additional information about the environment sending the message. You can ignore it if you are using the direct HTTP API method
timestamp	String	Optional	ISO-8601 format date string to record historical data. Eg: 2021-07-26T17:10:55.096Z
anonymous_id	String	Optional	Represent an unidentified or bot user. Recommended in uuidv4 format. Either anonymous_id or user_id must be set
user_id	String	Optional	The unique identifier of your user in your system. It normally is the database ID of that user or user's phone if you are having no user ID. Either anonymous_id or user_id must be set
event_params	Array	Optional	An array of Filum KV Items

Filum Item is a dictionary in the following convention:

{
  "key": "Example Name",
  "value": {
     "string_value": "Example String Value"
   }
}

The value can have the following types: string_value, int_value, double_value and datetime_value

Name	Data Type	Example
string_value	String	"Example Name"
int_value	Integer	11
double_value	Float/Double	3.1419

Identify

Method and endpoint to send request to:

POST https://event.filum.ai/events

Example data to transfer:

JSON payload

{
  "timestamp": "2024-07-15T07:58:13Z",
  "user_id": "0123456789",
  "event_name": "Identify",
  "event_type": "identify",
  "event_params": [
    {
      "key": "Name",
      "value": {
        "string_value": "Harry Potter"
      }
    },
    {
      "key": "Email",
      "value": {
        "string_value": "harry@filum.ai"
      }
    },
    {
      "key": "Phone",
      "value": {
        "string_value": "0123456789"
      }
    }
  ]
}

Node.js

const axios = require('axios');

// Replace 'YOUR_WRITEKEY' with your actual write key
const WRITEKEY = 'YOUR_WRITEKEY';

// Data to be sent
const data = {
  timestamp: "2024-07-15T07:58:13Z",
  user_id: "0123456789",
  event_name: "Identify",
  event_type: "identify",
  event_params: [
    {
      key: "Name",
      value: {
        string_value: "Harry Potter"
      }
    },
    {
      key: "Email",
      value: {
        string_value: "harry@filum.ai"
      }
    },
    {
      key: "Phone",
      value: {
        string_value: "0123456789"
      }
    }
  ]
};

// Configuring the request
const config = {
  headers: {
    'Authorization': 'Bearer ' + WRITEKEY,
    'Content-Type': 'application/json'
  }
};

// Sending the POST request
axios.post('https://event.filum.ai/events', data, config)
  .then(response => {
    console.log('Response:', response.data);
  })
  .catch(error => {
    console.error('Error:', error.response ? error.response.data : error.message);
  });

Python

import requests
import json

# Replace 'YOUR_WRITEKEY' with your actual write key
write_key = 'YOUR_WRITEKEY'

# Define the headers
headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {write_key}'
}

# Define the data to be sent
data = {
    "timestamp": "2024-07-15T07:58:13Z",
    "user_id": "0123456789",
    "event_name": "Identify",
    "event_type": "identify",
    "event_params": [
        {
            "key": "Name",
            "value": {
                "string_value": "Harry Potter"
            }
        },
        {
            "key": "Email",
            "value": {
                "string_value": "harry@filum.ai"
            }
        },
        {
            "key": "Phone",
            "value": {
                "string_value": "0123456789"
            }
        }
    ]
}

# Define the URL
url = "https://event.filum.ai/events"

# Send the POST request
response = requests.post(url, headers=headers, data=json.dumps(data))

# Print the response status code and content
print("Status Code:", response.status_code)
print("Response Content:", response.content.decode())

PHP

<?php
// Define the data to be sent
$data = [
    "timestamp" => "2024-07-15T07:58:13Z",
    "user_id" => "0123456789",
    "event_name" => "Identify",
    "event_type" => "identify",
    "event_params" => [
        [
            "key" => "Name",
            "value" => [
                "string_value" => "Harry Potter"
            ]
        ],
        [
            "key" => "Email",
            "value" => [
                "string_value" => "harry@filum.ai"
            ]
        ],
        [
            "key" => "Phone",
            "value" => [
                "string_value" => "0123456789"
            ]
        ]
    ]
];

// Convert data to JSON
$data_json = json_encode($data);

// Define the URL to send data to
$url = 'https://event.filum.ai/events';

// Your write key
$write_key = 'YOUR_WRITEKEY';

// Initialize cURL session
$ch = curl_init($url);

// Set cURL options
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $write_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);

// Execute cURL request
$response = curl_exec($ch);

// Check for errors
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    echo 'Response:' . $response;
}

// Close cURL session
curl_close($ch);
?>

.NET

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace SendEvent
{
    class Program
    {
        static async Task Main(string[] args)
        {
            var httpClient = new HttpClient();

            var url = "https://event.filum.ai/events";
            var writeKey = "YOUR_WRITEKEY"; // Replace with your actual Write Key
            var authorizationHeader = "Bearer " + writeKey;

            var eventData = new
            {
                timestamp = "2024-07-15T07:58:13Z",
                user_id = "0123456789",
                event_name = "Identify",
                event_type = "identify",
                event_params = new[]
                {
                    new { key = "Name", value = new { string_value = "Harry Potter" } },
                    new { key = "Email", value = new { string_value = "harry@filum.ai" } },
                    new { key = "Phone", value = new { string_value = "0123456789" } },
                }
            };

            var json = Newtonsoft.Json.JsonConvert.SerializeObject(eventData);
            var content = new StringContent(json, Encoding.UTF8, "application/json");

            httpClient.DefaultRequestHeaders.Clear();
            httpClient.DefaultRequestHeaders.Add("Authorization", authorizationHeader);

            HttpResponseMessage response = await httpClient.PostAsync(url, content);

            if (response.IsSuccessStatusCode)
            {
                Console.WriteLine("Event sent successfully.");
            }
            else
            {
                var responseContent = await response.Content.ReadAsStringAsync();
                Console.WriteLine($"Failed to send event. Status Code: {response.StatusCode}, Response: {responseContent}");
            }
        }
    }
}

Java

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;

public class PostEvent {
    public static void main(String[] args) {
        try {
            // Set your write key here
            String writeKey = "YOUR_WRITEKEY";

            // URL for the API endpoint
            String apiUrl = "https://event.filum.ai/events";

            // JSON payload
            String jsonInputString = "{\n" +
                    "  \"timestamp\": \"2024-07-15T07:58:13Z\",\n" +
                    "  \"user_id\": \"0123456789\",\n" +
                    "  \"event_name\": \"Identify\",\n" +
                    "  \"event_type\": \"identify\",\n" +
                    "  \"event_params\": [\n" +
                    "    {\n" +
                    "      \"key\": \"Name\",\n" +
                    "      \"value\": {\n" +
                    "        \"string_value\": \"Harry Potter\"\n" +
                    "      }\n" +
                    "    },\n" +
                    "    {\n" +
                    "      \"key\": \"Email\",\n" +
                    "      \"value\": {\n" +
                    "        \"string_value\": \"harry@filum.ai\"\n" +
                    "      }\n" +
                    "    },\n" +
                    "    {\n" +
                    "      \"key\": \"Phone\",\n" +
                    "      \"value\": {\n" +
                    "        \"string_value\": \"0123456789\"\n" +
                    "      }\n" +
                    "    }\n" +
                    "  ]\n" +
                    "}";

            // Create URL object
            URL url = new URL(apiUrl);
            HttpURLConnection con = (HttpURLConnection) url.openConnection();

            // Set request method to POST
            con.setRequestMethod("POST");

            // Set request headers
            con.setRequestProperty("Authorization", "Bearer " + writeKey);
            con.setRequestProperty("Content-Type", "application/json; utf-8");
            con.setRequestProperty("Accept", "application/json");

            // Enable the input and output streams
            con.setDoOutput(true);

            // Write the JSON input to OutputStream
            try (OutputStream os = con.getOutputStream()) {
                byte[] input = jsonInputString.getBytes("utf-8");
                os.write(input, 0, input.length);
            }

            // Get the response code for debugging purposes
            int responseCode = con.getResponseCode();
            System.out.println("Response Code: " + responseCode);

            // (Optional) Read the response from the server (not shown here)
            // ...

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Track

Method and endpoint to send request to:

POST https://event.filum.ai/events

Example data to transfer:

JSON payload

{
  "timestamp": "2024-07-15T07:58:13Z",
  "user_id": "0123456789",
  "event_name": "Transaction Completed",
  "event_type": "track",
  "event_params": [
    {
      "key": "Location Name",
      "value": {
        "string_value": "Hà Nội"
      }
    },
    {
      "key": "User Name",
      "value": {
        "string_value": "Harry Potter"
      }
    },
    {
      "key": "User Phone",
      "value": {
        "string_value": "0123456789"
      }
    },
    {
      "key": "Transaction ID",
      "value": {
        "string_value": "A005295008DX1"
      }
    },
    {
      "key": "Total Value",
      "value": {
        "double_value": 1451000
      }
    },
    {
      "key": "Note",
      "value": {
        "string_value": "Bảo hảnh 12 tháng"
      }
    },
    {
      "key": "Source",
      "value": {
        "string_value": "Online"
      }
    }
  ]
}

Node.js

const axios = require('axios');

// Replace with your actual write key
const YOUR_WRITEKEY = 'YOUR_WRITE_KEY_HERE';

const eventData = {
  "timestamp": "2024-07-15T07:58:13Z",
  "user_id": "0123456789",
  "event_name": "Transaction Completed",
  "event_type": "track",
  "event_params": [
    {
      "key": "Location Name",
      "value": {
        "string_value": "Hà Nội"
      }
    },
    {
      "key": "User Name",
      "value": {
        "string_value": "Harry Potter"
      }
    },
    {
      "key": "User Phone",
      "value": {
        "string_value": "0123456789"
      }
    },
    {
      "key": "Transaction ID",
      "value": {
        "string_value": "A005295008DX1"
      }
    },
    {
      "key": "Total Value",
      "value": {
        "double_value": 1451000
      }
    },
    {
      "key": "Note",
      "value": {
        "string_value": "Bảo hảnh 12 tháng"
      }
    },
    {
      "key": "Source",
      "value": {
        "string_value": "Online"
      }
    }
  ]
};

axios.post('https://event.filum.ai/events', eventData, {
  headers: {
    'Authorization': `Bearer ${YOUR_WRITEKEY}`,
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log('Event sent successfully:', response.data);
})
.catch(error => {
  console.error('Error sending event:', error.response ? error.response.data : error.message);
});

Python

import requests
import json

# Replace YOUR_WRITEKEY with your actual write key
YOUR_WRITEKEY = 'YOUR_WRITEKEY'

url = 'https://event.filum.ai/events'
headers = {
    'Authorization': f'Bearer {YOUR_WRITEKEY}',
    'Content-Type': 'application/json'
}

data = {
    "timestamp": "2024-07-15T07:58:13Z",
    "user_id": "0123456789",
    "event_name": "Transaction Completed",
    "event_type": "track",
    "event_params": [
        {
            "key": "Location Name",
            "value": {
                "string_value": "Hà Nội"
            }
        },
        {
            "key": "User Name",
            "value": {
                "string_value": "Harry Potter"
            }
        },
        {
            "key": "User Phone",
            "value": {
                "string_value": "0123456789"
            }
        },
        {
            "key": "Transaction ID",
            "value": {
                "string_value": "A005295008DX1"
            }
        },
        {
            "key": "Total Value",
            "value": {
                "double_value": 1451000
            }
        },
        {
            "key": "Note",
            "value": {
                "string_value": "Bảo hảnh 12 tháng"
            }
        },
        {
            "key": "Source",
            "value": {
                "string_value": "Online"
            }
        }
    ]
}

response = requests.post(url, headers=headers, data=json.dumps(data))

# Print the response
print(f'Status Code: {response.status_code}')
print(f'Response Text: {response.text}')

PHP

<?php

// Define the data array
$data = [
    "timestamp" => "2024-07-15T07:58:13Z",
    "user_id" => "0123456789",
    "event_name" => "Transaction Completed",
    "event_type" => "track",
    "event_params" => [
        [
            "key" => "Location Name",
            "value" => [
                "string_value" => "Hà Nội"
            ]
        ],
        [
            "key" => "User Name",
            "value" => [
                "string_value" => "Harry Potter"
            ]
        ],
        [
            "key" => "User Phone",
            "value" => [
                "string_value" => "0123456789"
            ]
        ],
        [
            "key" => "Transaction ID",
            "value" => [
                "string_value" => "A005295008DX1"
            ]
        ],
        [
            "key" => "Total Value",
            "value" => [
                "double_value" => 1451000
            ]
        ],
        [
            "key" => "Note",
            "value" => [
                "string_value" => "Bảo hảnh 12 tháng"
            ]
        ],
        [
            "key" => "Source",
            "value" => [
                "string_value" => "Online"
            ]
        ]
    ]
];

// Convert the data array to JSON
$jsonData = json_encode($data);

// Define the URL to send the POST request
$url = 'https://event.filum.ai/events';

// Define your write key here
$writeKey = 'YOUR_WRITEKEY';

// Initialize cURL session
$ch = curl_init($url);

// Set the cURL options
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $writeKey
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);

// Execute the cURL request
$response = curl_exec($ch);

// Check for errors
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    echo 'Response:' . $response;
}

// Close the cURL session
curl_close($ch);
?>

.NET

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace EventSender
{
    class Program
    {
        private static readonly HttpClient client = new HttpClient();

        static async Task Main(string[] args)
        {
            string url = "https://event.filum.ai/events";
            string writeKey = "YOUR_WRITEKEY";  // Replace with your actual write key

            var data = new
            {
                timestamp = "2024-07-15T07:58:13Z",
                user_id = "0123456789",
                event_name = "Transaction Completed",
                event_type = "track",
                event_params = new[]
                {
                    new { key = "Location Name", value = new { string_value = "Hà Nội" } },
                    new { key = "User Name", value = new { string_value = "Harry Potter" } },
                    new { key = "User Phone", value = new { string_value = "0123456789" } },
                    new { key = "Transaction ID", value = new { string_value = "A005295008DX1" } },
                    new { key = "Total Value", value = new { double_value = 1451000 } },
                    new { key = "Note", value = new { string_value = "Bảo hảnh 12 tháng" } },
                    new { key = "Source", value = new { string_value = "Online" } }
                }
            };

            var json = Newtonsoft.Json.JsonConvert.SerializeObject(data);
            var content = new StringContent(json, Encoding.UTF8, "application/json");

            client.DefaultRequestHeaders.Add("Authorization", $"Bearer {writeKey}");

            var response = await client.PostAsync(url, content);

            if (response.IsSuccessStatusCode)
            {
                Console.WriteLine("Event sent successfully.");
            }
            else
            {
                Console.WriteLine($"Failed to send event. Status code: {response.StatusCode}");
                var responseContent = await response.Content.ReadAsStringAsync();
                Console.WriteLine($"Response: {responseContent}");
            }
        }
    }
}

Java

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;

public class SendEventData {

    public static void main(String[] args) {
        String jsonInputString = "{\n" +
                "    \"timestamp\": \"2024-07-15T07:58:13Z\",\n" +
                "    \"user_id\": \"0123456789\",\n" +
                "    \"event_name\": \"Transaction Completed\",\n" +
                "    \"event_type\": \"track\",\n" +
                "    \"event_params\": [\n" +
                "      {\n" +
                "        \"key\": \"Location Name\",\n" +
                "        \"value\": {\n" +
                "          \"string_value\": \"Hà Nội\"\n" +
                "        }\n" +
                "      },\n" +
                "      {\n" +
                "        \"key\": \"User Name\",\n" +
                "        \"value\": {\n" +
                "          \"string_value\": \"Harry Potter\"\n" +
                "        }\n" +
                "      },\n" +
                "      {\n" +
                "        \"key\": \"User Phone\",\n" +
                "        \"value\": {\n" +
                "          \"string_value\": \"0123456789\"\n" +
                "        }\n" +
                "      },\n" +
                "      {\n" +
                "        \"key\": \"Transaction ID\",\n" +
                "        \"value\": {\n" +
                "          \"string_value\": \"A005295008DX1\"\n" +
                "        }\n" +
                "      },\n" +
                "      {\n" +
                "        \"key\": \"Total Value\",\n" +
                "        \"value\": {\n" +
                "          \"double_value\": 1451000\n" +
                "        }\n" +
                "      },\n" +
                "      {\n" +
                "        \"key\": \"Note\",\n" +
                "        \"value\": {\n" +
                "          \"string_value\": \"Bảo hảnh 12 tháng\"\n" +
                "        }\n" +
                "      },\n" +
                "      {\n" +
                "        \"key\": \"Source\",\n" +
                "        \"value\": {\n" +
                "          \"string_value\": \"Online\"\n" +
                "        }\n" +
                "      }\n" +
                "    ]\n" +
                "  }";

        String apiUrl = "https://event.filum.ai/events";
        String authorizationHeader = "Bearer YOUR_WRITEKEY"; // Replace with your actual key

        try {
            URL url = new URL(apiUrl);
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            con.setRequestMethod("POST");
            con.setRequestProperty("Content-Type", "application/json; utf-8");
            con.setRequestProperty("Authorization", authorizationHeader);
            con.setDoOutput(true);

            try (OutputStream os = con.getOutputStream()) {
                byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
                os.write(input, 0, input.length);
            }

            int code = con.getResponseCode();
            System.out.println("Response Code: " + code);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}