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. Log into your Fyno Application and from the top right corner, click on your profile icon. On the menu that drops down, click on "Workspace Settings". On the page that loads, find "Allowlist URL" from the ribbon menu.
  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 link 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.
      2. Optional Token: A token that you can specify 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.
    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 system network Administrator. A general guide on how to do this can be found here.
    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 Send DLR 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.

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

ParameterType and Value
enableDefault: true,
true: enable delivery status over callback.
false: disable delivery status over callback
custom_idstring; an alpha-numeric unique identifier of your notification.
Length: 100 characters
custom1string; (Optional) additional information that you want to tag your notification.
Example: order-id
Length: 30 characters
custom2string; (Optional) additional information that you want to tag your notification.
Example: Category
Length: 30 characters
{
   "event": "YOUR_EVENT_NAME",
   "to": { // you channel destination },
   "data": {  // your template placeholders  },
   "callback": {
       "custom_id": "YOUR_CUSTOM_ID_VALUE",
    }
}

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

Parameter NameType & Value
custom_idString; an alpha-numeric unique identifier that is provided in the callback object during the submission request
msg_idString; Fyno message id that is generated during submission request.
example : 17f7e491-f51f-4e1e-881c-794f838c7c3c:s8a5
statusString; It holds the delivery status information of the triggered message id.
Example: DELIVERED, FAILED, READ, OPEN, etc

Additional Paramters

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.

Parameter NameType & Value
request_idstring; request_id parameter in response which is generated during the submission request
example: 17f7e491-f51f-4e1e-881c-794f838c7c3c
custom_idString; an alpha-numeric unique identifier that is provided in the callback object during the submission request
msg_idString; Fyno message id that is generated during submission request.
example : 17f7e491-f51f-4e1e-881c-794f838c7c3c:s8a5
statusString; It holds the delivery status information of the triggered message id.
Example: DELIVERED, FAILED, READ, OPEN, etc
destinationString; Fyno message id that is generated during submission request.
example : 17f7e491-f51f-4e1e-881c-794f838c7c3c:s8a5
messageString; This is an error message given by the provider if any delivery failure occurs.
Note: all provider does not give this information
senttimeString; Submission time of the request, YYYY-MM-DD hh:mm:ss UTC
dlrtimeString; Submission time of the request, YYYY-MM-DD hh:mm:ss UTC
integration_nameString; Integration account name through which the notification was sent
channelString; the name of the channel through which the notification was sent
providerString; the name of the provider via which the notification was sent
event_nameString; the name of the Notification Event that is being triggered
templateString; the name of the Template, whose content is sent out delivery and ideally it is being configured in the notification event
versionString: API version that is used to trigger a notification event
test or live
custom1String: custom1 value that is submitted callback object in submission request. If it does not pass in the request then it will be an empty string
custom2String: custom2 value that is submitted callback object in submission request. If it does not pass in the request then it will be an empty string

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