{"type":"doc","content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Store Registration and Access Credential Generation:","type":"text"}]},{"type":"paragraph","content":[{"text":"As part of the store registration, Fenix will generate the ","type":"text"},{"text":"Client ID","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":", ","type":"text"},{"text":"Client Secret","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":", and ","type":"text"},{"text":"Access Token","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" 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.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Generated Dummy Access Credentials:","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"cee5bca8-c8e2-4f81-9ee9-ef0bf744bd45"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#deebff","rowspan":1,"colwidth":[137.0]},"content":[{"type":"paragraph","content":[{"text":"Store Name","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[621.0]},"content":[{"type":"paragraph","content":[{"text":"wearhumans.myshopify.com","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#deebff","rowspan":1,"colwidth":[137.0]},"content":[{"type":"paragraph","content":[{"text":"Client Id","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[621.0]},"content":[{"type":"paragraph","content":[{"text":"A1b2-C3d4-E5f6-G7h8-I9J0","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#deebff","rowspan":1,"colwidth":[137.0]},"content":[{"type":"paragraph","content":[{"text":"Client Secret","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[621.0]},"content":[{"type":"paragraph","content":[{"text":"AbCdEfGhIjKlMnOpQrS","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#deebff","rowspan":1,"colwidth":[137.0]},"content":[{"type":"paragraph","content":[{"text":"Access Token","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[621.0]},"content":[{"type":"paragraph","content":[{"text":"eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ","type":"text"}]}]}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"Access Token","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" is primarily used to interact with Fenix APIs. Fenix will authenticate API requests based on the Access Token included in the API headers.","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"Client Secret ","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":"is primarily used by client systems to validate whether requests are coming from the Fenix system or from unauthorized sources.","type":"text"},{"type":"hardBreak"},{"type":"hardBreak"},{"text":"Approach to validate the Fenix requests in client systems:","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Fenix will include a base64-encoded X-Fenix-Hmac-SHA256 field in the payload header, generated using the client secret and specific data ","type":"text"},{"text":"(Fenix will provide a sample codebase, including the data fields and format used)","type":"text","marks":[{"type":"textColor","attrs":{"color":"#0747a6"}},{"type":"em"}]},{"text":" 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.","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"The combination of the ","type":"text"},{"text":"Client ID","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" and ","type":"text"},{"text":"Client Secret","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" is used to refresh/rotate the Access Token for security purposes.","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Webhooks Registration:","type":"text"}]},{"type":"table","attrs":{"layout":"align-start","width":760.0,"localId":"82db4387-4b48-4d9d-a032-59d3d84d90ec"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"Method","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[579.0]},"content":[{"type":"paragraph","content":[{"text":"POST","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"Endpoint URL","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[579.0]},"content":[{"type":"paragraph","content":[{"text":"/admin/api/2024-07/webhooks","type":"text","marks":[{"type":"link","attrs":{"href":"#"}}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"Request Headers","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[579.0]},"content":[{"type":"paragraph","content":[{"text":"X-Access-Token: {access token provided by the Fenix}","type":"text"},{"type":"hardBreak"},{"text":"Content-Type: application/json","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"Request Payload","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[579.0]},"content":[{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"store_name\": \"wearhumans.myshopify.com\", \n \"topic\": \"tracking/updated\", \n \"address\": \"https://{localhost}/{repository_name}/shipment-track-status\", \n \"format\": \"JSON\", \n \"api_version\": \"2024.07\", \n \"filters\": [\n {\n \"attribute\": \"CARRIERS\", \n \"operator\": \"IN\", \n \"value\": [\n \"LASERSHIP\", \n \"Pitney Bowes\"\n ], \n \"sub_filter\": {\n \"attribute\": \"DELIVERY STATUES\", \n \"operator\": \"IN\", \n \"value\": [\n \"PICKED_BY_CARRIER\", \n \"OUT_FOR_DELIVERY\", \n \"DELIVERED\"\n ]\n }\n }, \n {\n \"attribute\": \"CARRIERS\", \n \"operator\": \"IN\", \n \"value\": [\n \"FEDEX\"\n ], \n \"sub_filter\": {\n \"attribute\": \"DELIVERY STATUES\", \n \"operator\": \"IN\", \n \"value\": [\n \"DELIVERED\"\n ]\n }\n }\n ]\n}","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":2,"background":"#b3d4ff","rowspan":1,"colwidth":[180.0,579.0]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"center"}}],"content":[{"text":"Success Response","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"Code","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[579.0]},"content":[{"type":"paragraph","content":[{"text":"201","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"Payload","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[579.0]},"content":[{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"id\": \"77a56e05-dbc0-476d-8665-f33f34e963a1\", \n \"store_name\": \"wearhumans.myshopify.com\", \n \"topic\": \"tracking/updated\", \n \"address\": \"https://{localhost}/{repository_name}/shipment-track-status\", \n \"format\": \"JSON\", \n \"api_version\": \"2024-07\", \n \"created_dttm\": \"2024-07-05T17:45:30-05:00\", \n \"updated_dttm\": \"2024-07-05T17:45:30-05:00\", \n \"status\": \"ACTIVE/INACTIVE/DISABLED\", \n \"filters\": [\n {\n \"attribute\": \"CARRIERS\", \n \"operator\": \"IN\", \n \"value\": [\n \"LASERSHIP\", \n \"Pitney Bowes\"\n ], \n \"sub_filter\": {\n \"attribute\": \"DELIVERY STATUES\", \n \"operator\": \"IN\", \n \"value\": [\n \"PICKED_BY_CARRIER\", \n \"OUT_FOR_DELIVERY\", \n \"DELIVERED\"\n ]\n }\n }, \n {\n \"attribute\": \"CARRIERS\", \n \"operator\": \"IN\", \n \"value\": [\n \"FEDEX\"\n ], \n \"sub_filter\": {\n \"attribute\": \"DELIVERY STATUES\", \n \"operator\": \"IN\", \n \"value\": [\n \"DELIVERED\"\n ]\n }\n }\n ]\n} ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":2,"background":"#ffebe6","rowspan":1,"colwidth":[180.0,579.0]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"center"}}],"content":[{"text":"Error Response","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"Code","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[579.0]},"content":[{"type":"paragraph","content":[{"text":"400","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[180.0]},"content":[{"type":"paragraph","content":[{"text":"Payload","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[579.0]},"content":[{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"error_code\": \"400\", \n \"identifier\": \"INVALID_PARAMETERS\", \n \"error_message\": \"Invalid Store Name: wearhumans.myshopify.com\", \n \"description\": \"Storename is not registered with the Fenix\"\n}","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Client System API Endpoint Requirements","type":"text"}]},{"type":"table","attrs":{"layout":"align-start","width":760.0,"localId":"ac9abe97-e4b6-4856-8eb9-3aff597d847b"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[173.0]},"content":[{"type":"paragraph","content":[{"text":"Method","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[587.0]},"content":[{"type":"paragraph","content":[{"text":"POST","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[173.0]},"content":[{"type":"paragraph","content":[{"text":"Endpoint URL","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[587.0]},"content":[{"type":"paragraph","content":[{"text":"https://{localhost}/{repository_name}/shipment-track-status","type":"text","marks":[{"type":"link","attrs":{"href":"https://localhost/%7Brepository_name%7D/api/v1/%7Bstore_name%7D/shipment-track-status"}}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[173.0]},"content":[{"type":"paragraph","content":[{"text":"Request Headers","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[587.0]},"content":[{"type":"paragraph","content":[{"text":"Content-Type: ","type":"text","marks":[{"type":"strong"}]},{"text":" \t { application/json }","type":"text"},{"type":"hardBreak"},{"text":"X-Fenix-Topic: ","type":"text","marks":[{"type":"strong"}]},{"text":"\t { Subscribed topic name: tracking/updated }","type":"text"},{"type":"hardBreak"},{"text":"X-Fenix-Webhook-Id:","type":"text","marks":[{"type":"strong"}]},{"text":" { Registered webhook id }","type":"text"},{"type":"hardBreak"},{"text":"X-Client-Storename: ","type":"text","marks":[{"type":"strong"}]},{"text":"\t { Registered Store name Ex. wearhumans.myshopify.com }","type":"text"},{"type":"hardBreak"},{"text":"X-Fenix-Triggered-Dttm:\t","type":"text","marks":[{"type":"strong"}]},{"text":"\t{ Timestamp when Fenix triggers API for registered event Ex. ","type":"text"},{"text":"2024-07-06T01:12:34-05:00","type":"text","marks":[{"type":"em"}]},{"text":" } {ISO Date time}","type":"text"},{"type":"hardBreak"},{"text":"X-Fenix-API-Version:","type":"text","marks":[{"type":"strong"}]},{"text":"\t\t { Fenix API Version Ex.2024-07 }\t","type":"text"},{"type":"hardBreak"},{"text":"X-Fenix-Event-Id:","type":"text","marks":[{"type":"strong"}]},{"text":"\t\t\t { Pushed data event id. Event ID for client data retrieval from Fenix if initial acceptance or storage fails }","type":"text"},{"type":"hardBreak"},{"text":"X-Fenix-Hmac-Sha256:","type":"text","marks":[{"type":"strong"}]},{"text":"\t { Base64 encoded code with Client Secret using SHA256 to validate Fenix data push}","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[173.0]},"content":[{"type":"paragraph","content":[{"text":"Request Payload","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[587.0]},"content":[{"type":"paragraph","content":[{"text":"The payload will vary depending on the registered topic","type":"text"},{"type":"hardBreak"},{"text":"Payload","type":"text","marks":[{"type":"link","attrs":{"href":"https://fenixcommerce.atlassian.net/wiki/spaces/FFL/pages/1914765316"}}]},{"text":" for ","type":"text"},{"text":"tracking/updated","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" topic.","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":2,"background":"#deebff","rowspan":1,"colwidth":[173.0,587.0]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"center"}}],"content":[{"text":"Success Response ","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[173.0]},"content":[{"type":"paragraph","content":[{"text":"Code","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[587.0]},"content":[{"type":"paragraph","content":[{"text":"200","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[173.0]},"content":[{"type":"paragraph","content":[{"text":"Response Time","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[587.0]},"content":[{"type":"paragraph","content":[{"text":"< X milli seconds","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":2,"background":"#ffebe6","rowspan":1,"colwidth":[173.0,587.0]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"center"}}],"content":[{"text":"Failure Response","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[173.0]},"content":[{"type":"paragraph","content":[{"text":"Code","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[587.0]},"content":[{"type":"paragraph","content":[{"text":"400","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[173.0]},"content":[{"type":"paragraph","content":[{"text":"Payload","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[587.0]},"content":[{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\n \"error_code\": \"400\", \n \"identifier\": \"INVALID_PARAMETERS\", \n \"error_message\": \"Invalid Hmac Sha256 code\", \n \"description\": \"Hmac Sha256 code is not matched internally\"\n}","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"How Fenix Generating the Hmac Sha 256 Code?","type":"text"}]},{"type":"codeBlock","attrs":{"language":"java"},"content":[{"text":"package com.fenix.commerce.delest.utils;\n\nimport javax.crypto.Mac;\nimport javax.crypto.spec.SecretKeySpec;\n\nimport org.apache.commons.codec.binary.Hex;\n\n/**\n * \n * @author srinivasa\n *\n */\npublic class HmacSha256CodeGenerator {\n\n\tprivate final static String HMAC256_KEY = \"HmacSHA256\";\n\tprivate final static String UTF_8 = \"UTF-8\";\n\n\t/**\n\t * \n\t * @param storeName,\n\t *

\n\t * it's header field: X-Client-Storename \n\t * @param webhookId,\n\t *

\n\t * it's header field: X-Fenix-Webhook-Id \n\t * @param eventId,\n\t *

\n\t * it's header field: X-Fenix-Event-Id \n\t * @param triggeredDttm,\n\t *

\n\t * it's header field:\n\t * X-Fenix-Triggered-Dttm \n\t * @param clientSecret,\n\t *

\n\t * it's a secret created and shared by the Fenix team\n\t * during the store registration process\n\t * @return\n\t *

\n\t * generated encoded Hmac Sha256 code\n\t */\n\tpublic static String generateEncodedCode(String storeName, String webhookId, String eventId, String triggeredDttm,\n\t\t\tString clientSecret) {\n\n\t\tString generatedHmacSha25Code = null;\n\t\tString dataToEncode = storeName + webhookId + eventId + triggeredDttm;\n\n\t\ttry {\n\t\t\tMac sha256_HMAC = Mac.getInstance(HMAC256_KEY);\n\t\t\tSecretKeySpec secret_key = new SecretKeySpec(clientSecret.getBytes(UTF_8), HMAC256_KEY);\n\t\t\tsha256_HMAC.init(secret_key);\n\t\t\tgeneratedHmacSha25Code = new String(\n\t\t\t\t\tHex.encodeHexString((sha256_HMAC.doFinal(dataToEncode.getBytes(UTF_8)))));\n\t\t} catch (Exception e) {\n\t\t\tLogUtils.throwableErrorLog.accept(CommonUtils.methodName.get(), e);\n\t\t}\n\t\treturn generatedHmacSha25Code;\n\t}\n\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"How client systems verify the HMAC code to authenticate the data source?","type":"text"}]},{"type":"paragraph","content":[{"text":"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 \"","type":"text"},{"text":"Invalid Source: Unmatched HMAC code","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":"\".","type":"text"}]},{"type":"codeBlock","attrs":{"language":"plaintext"},"content":[{"text":"Client Generated Hmac Sha256 Code == Fenix Provided Hmac Sha256 Code","type":"text"}]}],"version":1}

Browser not supported