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:
- Tap on Workspace Settings on the bottom left corner of the navigation menu and click 'Allowlist URL' which opens up the Allowlist URL page.
- 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".
- On doing so, a new pop-up will appear, wherein you will be prompted to verify the URL by one of 3 methods:
- 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:
- 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
- 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.
- 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.com
and then addhttps://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. - 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:
- 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.
- 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.
- 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.
![](https://files.readme.io/6f76a0e-Default_Delivery_Callback.png)
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
Parameter | Type and Value |
---|---|
enable | Default: true, true: enable delivery status over callback. false: disable delivery status over callback |
custom_id | string; an alpha-numeric unique identifier of your notification. Length: 200 characters OR number; numeric unique identifier of your notification. Length: 20 digits |
custom1 | string; (Optional) additional information that you want to tag your notification. Example: order-id Length: 50 characters |
custom2 | string; (Optional) additional information that you want to tag your notification. Example: Category Length: 50 characters |
allowlist_url | string; (Optional) Allowlist url name where you want to receive delivery reports. Can be array of Allowlist url name too if you want the delivery reports in multiple URLs. Example: ["DynamicWebhookSite", "Mixpanel"] |
{
"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
Parameter Name | Type & Value |
---|---|
custom_id | String or Number; an alpha-numeric or numeric unique identifier that is provided in the callback object during the submission request |
msg_id | String; Fyno message id that is generated during submission request. example : 17f7e491-f51f-4e1e-881c-794f838c7c3c:s8a5 |
status | String; It holds the delivery status information of the triggered message id. Example: DELIVERED, FAILED, READ, OPEN, etc |
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.
Parameter Name | Type & Value |
---|---|
request_id | string; request_id parameter in response which is generated during the submission request example: 17f7e491-f51f-4e1e-881c-794f838c7c3c |
custom_id | String or Number; an alpha-numeric or numeric unique identifier that is provided in the callback object during the submission request. |
msg_id | String; Fyno message id that is generated during submission request. example : 17f7e491-f51f-4e1e-881c-794f838c7c3c:s8a5 |
status | String; It holds the delivery status information of the triggered message id. Example: DELIVERED, FAILED, READ, OPEN, etc |
destination | String; destinations like email, mobile no sent during submission request. example : [email protected], 919876543210 |
distinct_id | String; It holds the distinct_id of the user, if specified in the request |
message | String; This is an error message given by the provider if any delivery failure occurs. Note: all provider does not give this information |
senttime | String; Submission time of the request, YYYY-MM-DD HH:mm:ss UTC |
senttime_epoch | String; Submission time of the request in epoch format (Unix time) |
dlrtime | String; The time when the delivery report status was received, YYYY-MM-DD HH:mm:ss UTC |
dlrtime_epoch | String; The time when the delivery report status was received in epoch format (Unix time) |
integration_name | String; Integration account name through which the notification was sent |
channel | String; the name of the channel through which the notification was sent |
provider | String; the name of the provider via which the notification was sent |
event_name | String; the name of the Notification Event that is being triggered |
template | String; the name of the Template, whose content is sent out delivery and ideally it is being configured in the notification event |
version | String: API version that is used to trigger a notification event test or live |
custom1 | String: 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 |
custom2 | String: 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"
}
Updated 3 months ago