Skip to main content

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:

PropertyTypeRequiredDescription
event_typeStringRequiredidentify for Identify call and track for Track call
event_nameStringRequired- Identify for Identify call and a meaningful name for Track call (Eg: Order Completed, Transaction Failed or eKYC Result Returned etc.)
contextObjectOptionalContains additional information about the environment sending the message. You can ignore it if you are using the direct HTTP API method
timestampStringOptionalISO-8601 format date string to record historical data. Eg: 2021-07-26T17:10:55.096Z
anonymous_idStringOptionalRepresent an unidentified or bot user. Recommended in uuidv4 format. Either anonymous_id or user_id must be set
user_idStringOptionalThe 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_paramsArrayOptionalAn 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

NameData TypeExample
string_valueString"Example Name"
int_valueInteger11
double_valueFloat/Double3.1419

Identify

Method and endpoint to send request to:

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

Example data to transfer:

{
"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"
}
}
]
}

Track

Method and endpoint to send request to:

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

Example data to transfer:

{
"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"
}
}
]
}