Fenix 'Tracking/Update' Webhook
- Srinivas Aluri
Store Registration and Access Credential Generation:
As part of the store registration, Fenix will generate the Client ID, Client Secret, and Access Token for each store and share them with the store owner. In the future, Fenix will provide a user interface and an API for store registration with Fenix, allowing store owners to register their stores in the Fenix directly through either the UI or the API.
Generated Dummy Access Credentials:
Store Name | wearhumans.myshopify.com |
Client Id | A1b2-C3d4-E5f6-G7h8-I9J0 |
Client Secret | AbCdEfGhIjKlMnOpQrS |
Access Token | eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ |
The Access Token is primarily used to interact with Fenix APIs. Fenix will authenticate API requests based on the Access Token included in the API headers.
The Client Secret is primarily used by client systems to validate whether requests are coming from the Fenix system or from unauthorized sources.
Approach to validate the Fenix requests in client systems:
Fenix will include a base64-encoded X-Fenix-Hmac-SHA256 field in the payload header, generated using the client secret and specific data (Fenix will provide a sample codebase, including the data fields and format used) to generate the code separately for each webhook topic). Client systems should replicate this process to generate the base64-encoded code and compare it with the code provided by Fenix to validate whether the request is coming from Fenix or not.
The combination of the Client ID and Client Secret is used to refresh/rotate the Access Token for security purposes.
Webhooks Registration:
Method | POST |
Endpoint URL | |
Request Headers | X-Access-Token: {access token provided by the Fenix} |
Request Payload | {
"store_name": "wearhumans.myshopify.com",
"topic": "tracking/updated",
"address": "https://{localhost}/{repository_name}/shipment-track-status",
"format": "JSON",
"api_version": "2024.07",
"filters": [
{
"attribute": "CARRIERS",
"operator": "IN",
"value": [
"LASERSHIP",
"Pitney Bowes"
],
"sub_filter": {
"attribute": "DELIVERY STATUES",
"operator": "IN",
"value": [
"PICKED_BY_CARRIER",
"OUT_FOR_DELIVERY",
"DELIVERED"
]
}
},
{
"attribute": "CARRIERS",
"operator": "IN",
"value": [
"FEDEX"
],
"sub_filter": {
"attribute": "DELIVERY STATUES",
"operator": "IN",
"value": [
"DELIVERED"
]
}
}
]
} |
Success Response | |
Code | 201 |
Payload | {
"id": "77a56e05-dbc0-476d-8665-f33f34e963a1",
"store_name": "wearhumans.myshopify.com",
"topic": "tracking/updated",
"address": "https://{localhost}/{repository_name}/shipment-track-status",
"format": "JSON",
"api_version": "2024-07",
"created_dttm": "2024-07-05T17:45:30-05:00",
"updated_dttm": "2024-07-05T17:45:30-05:00",
"status": "ACTIVE/INACTIVE/DISABLED",
"filters": [
{
"attribute": "CARRIERS",
"operator": "IN",
"value": [
"LASERSHIP",
"Pitney Bowes"
],
"sub_filter": {
"attribute": "DELIVERY STATUES",
"operator": "IN",
"value": [
"PICKED_BY_CARRIER",
"OUT_FOR_DELIVERY",
"DELIVERED"
]
}
},
{
"attribute": "CARRIERS",
"operator": "IN",
"value": [
"FEDEX"
],
"sub_filter": {
"attribute": "DELIVERY STATUES",
"operator": "IN",
"value": [
"DELIVERED"
]
}
}
]
} |
Error Response | |
Code | 400 |
Payload | {
"error_code": "400",
"identifier": "INVALID_PARAMETERS",
"error_message": "Invalid Store Name: wearhumans.myshopify.com",
"description": "Storename is not registered with the Fenix"
} |
Client System API Endpoint Requirements
Method | POST |
Endpoint URL | |
Request Headers | Content-Type: { application/json } |
Request Payload | The payload will vary depending on the registered topic |
Success Response | |
Code | 200 |
Response Time | < X milli seconds |
Failure Response | |
Code | 400 |
Payload | |
How Fenix Generating the Hmac Sha 256 Code?
How client systems verify the HMAC code to authenticate the data source?
Fenix generates the HMAC code and includes it in the HTTP headers when pushing data to client systems. The client systems then generate their own HMAC code using the same method and compare it with the HMAC code provided by Fenix. If both codes match, the data is verified as coming from Fenix, then process and store it your system. If they do not match, throw an error message like "Invalid Source: Unmatched HMAC code".