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 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 identifer of your user in your system. It normally is the database ID of that user. 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:

identify_payload = [
  {
    timestamp: '2021-07-26T17:10:55.096Z',
    user_id: '75442486-0878-440c-9db1-a7006c25a39f',
    event_name: 'Identify',
    event_type: 'identify',
    event_params: [
      {
        key: 'Name',
        value: {
          string_value: 'Harry Potter'
        }
      },
      {
        key: 'Created On',
        value: {
          datetime_value: '2021-07-26T17:10:55.096Z'
        }
      },
      {
        key: 'Integer Property',
        value: {
          int_value: 101
        }
      },
      {
        key: 'Float Property',
        value: {
          double_value: 113.53
        }
      }
    ]
  }
]

Track

Method and endpoint to send request to:

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

Example data to transfer:

track_payload = [
  {
    timestamp: '2021-07-26T17:10:55.096Z',
    user_id: '75442486-0878-440c-9db1-a7006c25a39f',
    event_name: 'Transaction Completed',
    event_type: 'track',
    event_params: [
      {
        key: 'Transaction ID',
        value: {
          string_value: '#001'
        }
      },
      {
        key: 'Created On',
        value: {
          string_value: '2021-07-26T17:10:55.096Z'
        }
      },
      {
        key: 'Total Value',
        value: {
          double_value: 1000000
        }
      }
    ]
  }
]