Allowlist URL

Allowlist in its definition itself is a list of URLs or APIs that you would need to add to the Fyno platform before you use it on the application and in your automations.

All URLs that you intend on using within the Fyno Application need to be added to the Allowlist before being plugged into the application.

The need for an Allowlist

Allowlists were designed for Fyno's app users to ensure security for the information that is being plugged into the system, by having verified URLs and thus help avoid unnecessary security hassles.

Pre-approving the URLs that you need to use in your integration ensures that no changes can happen in the integrations without actively making the changes and thus leaves very little room for error.

Creating an Allowlist URL

Adding or creating an Allowlist is a straightforward process with Fyno.

You can simply add any number of URLs that you intend on using in Fyno's application by following the below steps:

1. Tap on Workspace Settings on the bottom left corner of the navigation menu and click 'Allowlist URL' which opens up the Allowlist URL page.
2. On the page that opens, find the "Add URL" button on the right side of the page. Provide a relevant name and enter the URL that you intend on using and click on "Add and Verify".
3. On doing so, a new pop-up will appear, wherein you will be prompted to verify the URL by one of 3 methods:

1. Web Token: A web token is a simple process of Fyno checking if the URL that has been provided is valid by sending a token. This can be validated in 2 ways:
   1. System Generated Token: A random token will be created from the back-end when the request is generated from the Fyno Application. The expected result is that when the webhook is called, it should be able to respond with the same token key. You have to echo the value that you receive in the query parameter. For example:If you receive a GET request from Fyno with fyno_token=98765. Then, your API should respond with 98765
   2. Optional Token: If you want to protect the URL from being used in an unauthorized way, you can add an optional token. You can provide optional token in the field provided. This can be alpha-numeric. The validation process is the same where the expected result is that when the webhook is called, it should be able to respond with the same token key. For example. you have added '12345' as optional token, in that case the query parameter you will receive will befyno_token=98765&user_token=12345
      You can validate if the user_token has the value that you have set. If it is matching then echo the fyno_token value for successful verification. This optional token is added for additional security.
2. DNS Verification: With DNS verification, you would need to paste the TXT record, which can be copied from the same window, into your DNS configuration. This can usually be handled by your network administrator. A general guide on how to do this can be found here. If a domain is allow-listed once using this method, any URL's containing this domain are automatically allow-listed. For instance, if you allow-list https://api.example.comand then add https://api.example.com/v1/data, then the latter will be automatically allow-listed. This way you can add multiple variants of the endpoint to the allow-list without having to wait for verification to complete.
3. Send For Verification: If for any reason you are not able to verify via the above 2 methods, you can send the URL for manual verification to Fyno's team. Provide a relevant description for the link as well as what will be achieved with the link and our team will get back to you on this.

Once the URL is added and the verification is complete, this will now be available on Fyno's application interface, for you to use.

Creating Delivery Webhooks

A Delivery Webhook is nothing but an Allowlist URL that can receive updates from Fyno regarding the delivery status of the notifications sent out and easily share the delivery details with you, to a location of your convenience, pre-decided by you.

An Allowlist URL can be converted anytime to a Delivery Webhook, once it is successfully verified by following the below steps:

1. Navigate to the Allowlist page by clicking on the profile icon on the top right corner to open the menu and click on Workspace Settings and "Allowlist URL" on the ribbon menu and click on it. On the page that loads, find the link you want to tag as the Delivery Webhook.
2. If this Allowlist URL is not verified, follow the above mentioned steps. Once verified, click on the "More" (three dots) menu on the right side to find the option Configure and update delivery endpoint and click on it.
3. In the window that opens, you can add additional configurations, based on your requirements. You can also alternatively scroll to the bottom and save. This will send you the basic details that are pre-configured at Fyno's end.

The first Delivery Endpoint you create will be considered as 'Default' and you will start receiving your delivery reports in that URL. At any point of time, there will be only one default Allowlist URL. If you want to receive delivery reports in other URLs other than default URLs, you need to specify it in the payload as explained in the next section.

Once this is done, all the delivery statuses for every notification triggered will be automatically updated at this location.

🚧

Not all Providers and Channels give you delivery notifications and updates. Check here for a detailed list

Callback Objects in a Request

{
   "event": "YOUR_EVENT_NAME",
   "to": { // you channel destination },
   "data": {  // your template placeholders  },
   "callback": {
       "custom_id": "YOUR_CUSTOM_ID_VALUE",
       "custom1":"3d066514-c55d-48f8-b7ff-3981a43c20d4",
       "allowlist_url": ["DynamicWebhookSite", "Mixpanel"]
    }
}

Callback Response

Here's a list of default fields which will be sent if the delivery status callback is subscribed using Webhook URL" with "Callback Object" in the request:

The Delivery Webhook will be sent using:

Method: POST | GET
Content-Type : application/x-www-form-urlencoded | application/json
Data: Default Parameters + Additional Parameters

Default Parameters

Additional Parameters

Additional Parameters can be sent in the response by configuring the same in your "Delivery Webhook" URL. All you will need to do is configure it as a Placeholder as shown in the sample payload below.

This configuration needs to be done in the payload section when converting an Allowlist URL to a Delivery Webhook

Here is a sample payload for reference.

{
     "param1": "{{destination}}",
     "param2": "{{provider}}",
     "param6": "{{integration_name}}",
      …………
}

Below is a list of all the parameters that Fyno can send you as data points. However, each one of these will need to be specified if you need them.

Sample Webhook Configuration and Response

Sample configuration for the additional parameters (JSON) in Webhooks Delivery status section

{
       "url": "https://webhook.site/847c54cc-c471-40f4-b793-36c18a",
       "method": "post",
       "headers": {
           "Content-Type": "application/json"
       },
       "data": {
           "recipent": "{{destination}}",
           "providername": "{{provider}}",
           "message": "{{message}}",
           "request_time": "{{senttime}}",
           "delivery_time": "{{dlrtime}}",
           "account_name": "{{integration_name}}",
           "reference_msg_id": "{{custom_id}}",
           "order_id": "{{custom1}}",
           "category": "{{custom2}}",
           "channel": "{{channel}}"
       }
}

Once this is successfully configured, here is a sample of the Callback Response you would receive.

{
       "msg_id": "FYNO_MSG_ID_UUID",
       "status": "DELIVERED",
       "custom_id": "YOUR_CUSTOM_ID_VALUE",
       "recipent": "[email protected]",
       "providername": "sendgrid",
       "message": "",
       "requesttime": "2023-03-24 10:23:39",
       "deliverytime": "2023-03-24 10:23:50",
       "account_name": "EmailProduction",
       "reference_msg_id": "YOUR_CUSTOM_ID_VALUE",
       "order_id": "YOUR_CUSTOM1_VALUE",
       "category": "YOUR_CUSTOM2_VALUE",
       "channel": "email"
}