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