Configuring Allowlist URL/SQS to receive Delivery Report

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 while adding Allowlist URL/SQS.

1Select the ‘Configure as Delivery Endpoint’ by clicking the ellipsis as shown.

2In the window that opens, you can select the checkbox ‘Set as default endpoint to receive delivery endpoints’

3Select the Method as ‘POST’

4Optionally you can add any Header params

5Choose Content Type from one of the options : application/json | multipart/form-data | application/x-www-form-urlencoded

6You can add the data points you want to receive in the Payload section and click ‘Confirm’

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 endpoint.

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

If you didn’t any parameters in the payload, Fyno will send the below default 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.

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 : abc@gmail.com, 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.
provider_msg_id	String; the msg ID (if available) of the provider via which the notification was sent.
provider_template_id	String; the provider template ID that was sent. For SMS, the DLT template ID is sent (for Indian businesses). For WhatsApp, the template name and language is sent (`templatename_lang`). For RCS, the template name is 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.
msg_content	JSON Object; Contains information of the template sent. For SMS, it will include the SMS text and template ID (if available). For WhatsApp, it will include the template_name, language, and placeholder mapping. For Email, it will include the subject line, body content, and attachments (only if Presigned/Public URLs are used).From Name, From Email and Reply To data points also will be received only if they are configured in the Email template. Note: This variable is enabled on request and is available only for SMS, WhatsApp and Email. If enabled, only the first webhook call will contain this variable.
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.
custom3	String: custom3 value that is submitted callback object in submission request. If it does not pass in the request then it will be an empty string.
params.useragent	String: It holds the user agent info for Email channel. Supported only for SES and Sendgrid providers. Ex - “UserAgent”: “Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36”.
params.ip	String: It holds IP address of the user clicking the URL sent as part of Email.
params.url	String: It holds URL clicked by the users sent as part of Email.
params.duration	String: It holds call duration of a Voice call in seconds.
params.recording_link	String: It holds call recording link of the a Voice Call.

Callback Objects in a Request

custom_id

stringRequired

Unique identifier of your notification.
Length: 200 characters if string. No special characters allowed.
Length: 20 digits if numeric.

custom1

string

Additional information to tag your notification.
Length: 50 characters. No special characters allowed.
Example: order-id.

custom2

string

Additional information to tag your notification.
Length: 50 characters. No special characters allowed.
Example: category.

custom3

string

Additional information to tag your notification.
Length: 50 characters. No special characters allowed.
Example: message-id.

enable

enumDefaults to true

true: enable delivery status over callback.
false: disable delivery status over callback.
The default value is true if custom_id is specified.

allowlist_url

string

Specify one or more allowlisted URL names (upto 3) where you want to receive delivery reports.
If no URL name(s) are specified here, the system will use your default URL (if one exists).
If no URL name(s) are specified here AND no default URL is set, delivery reports cannot be sent.
Example: ["DynamicWebhookSite", "Mixpanel"]
Example: DynamicWebhookSite

Sample Callback Objects in Request Parameters

1 {
2    "event": "YOUR_EVENT_NAME",
3    "to": { // you channel destination },
4    "data": {  // your template placeholders  },
5    "callback": {
6        "enable":true,
7        "custom_id": "YOUR_CUSTOM_ID_VALUE",
8        "custom1":"3d066514-c55d-48f8-b7ff-3981a43c20d4",
9        "allowlist_url": ["DynamicWebhookSite", "Mixpanel"]
10     }
11 }

Callback Response

The following contains list of default fields which will be sent if the payload for the delivery status callback is not defined.

The Delivery Webhook will be sent using:

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

Sample Webhook Configuration and Response

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

Sample Webhook Configuration

1 {
2   "url": "https://webhook.site/847c54cc-c471-40f4-b793-36c18a",
3   "method": "post",
4   "headers": {
5     "Content-Type": "application/json"
6   },
7   "data": {
8     "recipent": "{{destination}}",
9     "providername": "{{provider}}",
10     "provider_msg_id": "{{provider_msg_id}}",
11     "provider_template_id": "{{provider_template_id}}",
12     "message": "{{message}}",
13     "request_time": "{{senttime}}",
14     "delivery_time": "{{dlrtime}}",
15     "account_name": "{{integration_name}}",
16     "reference_msg_id": "{{custom_id}}",
17     "order_id": "{{custom1}}",
18     "category": "{{custom2}}",
19     "channel": "{{channel}}"
20   }
21 }

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

Sample Callback Response

1 {
2   "custom_id": "YOUR_CUSTOM_ID_VALUE",
3   "msg_id": "FYNO_MSG_ID_UUID",
4   "status": "DELIVERED",
5   "channel": "email",
6   "custom1": "YOUR_CUSTOM1_VALUE",
7   "custom2": "YOUR_CUSTOM2_VALUE",
8   "custom3": "YOUR_CUSTOM_ID_VALUE",
9   "destination": "user1@email.com",
10   "distinct_id": "user1@email.com",
11   "dlrtime": "2023-03-24 10:23:50",
12   "dlrtime_epoch": 1679653430,
13   "event_name": "DELIVERED",
14   "integration_name": "sendgrid",
15   "message": "",
16   "msg_content": "",
17   "params_duration": "",
18   "params_ip": "",
19   "params_recording_link": "",
20   "params_url": "",
21   "params_useragent": "",
22   "provider": "sendgrid",
23   "provider_msg_id": "1234567890",
24   "provider_template_id": "",
25   "request_id": "FYNO_MSG_ID_UUID",
26   "senttime": "2023-03-24 10:23:39",
27   "senttime_epoch": 1679653419,
28   "template": "",
29   "version": "1"
30 }

An Allowlist URL can be converted anytime to a Delivery Webhook, once it is successfully verified by following the below steps while adding Allowlist URL/SQS.

1Select the ‘Configure as Delivery Endpoint’ by clicking the ellipsis as shown.

2In the window that opens, you can select the checkbox ‘Set as default endpoint to receive delivery endpoints’

3Select the Method as ‘POST’

4Optionally you can add any Header params

5Choose Content Type from one of the options : application/json | multipart/form-data | application/x-www-form-urlencoded

6You can add the data points you want to receive in the Payload section and click ‘Confirm’

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

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

If you didn’t any parameters in the payload, Fyno will send the below default 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.

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 : abc@gmail.com, 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.
provider_msg_id	String; the msg ID (if available) of the provider via which the notification was sent.
provider_template_id	String; the provider template ID that was sent. For SMS, the DLT template ID is sent (for Indian businesses). For WhatsApp, the template name and language is sent (`templatename_lang`). For RCS, the template name is 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.
msg_content	JSON Object; Contains information of the template sent. For SMS, it will include the SMS text and template ID (if available). For WhatsApp, it will include the template_name, language, and placeholder mapping. For Email, it will include the subject line, body content, and attachments (only if Presigned/Public URLs are used).From Name, From Email and Reply To data points also will be received only if they are configured in the Email template. Note: This variable is enabled on request and is available only for SMS, WhatsApp and Email. If enabled, only the first webhook call will contain this variable.
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.
custom3	String: custom3 value that is submitted callback object in submission request. If it does not pass in the request then it will be an empty string.
params.useragent	String: It holds the user agent info for Email channel. Supported only for SES and Sendgrid providers. Ex - “UserAgent”: “Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36”.
params.ip	String: It holds IP address of the user clicking the URL sent as part of Email.
params.url	String: It holds URL clicked by the users sent as part of Email.
params.duration	String: It holds call duration of a Voice call in seconds.
params.recording_link	String: It holds call recording link of the a Voice Call.

Callback Objects in a Request

custom_id

stringRequired

Unique identifier of your notification.
Length: 200 characters if string. No special characters allowed.
Length: 20 digits if numeric.

custom1

string

Additional information to tag your notification.
Length: 50 characters. No special characters allowed.
Example: order-id.

custom2

string

Additional information to tag your notification.
Length: 50 characters. No special characters allowed.
Example: category.

custom3

string

Additional information to tag your notification.
Length: 50 characters. No special characters allowed.
Example: message-id.

enable

enumDefaults to true

true: enable delivery status over callback.
false: disable delivery status over callback.
The default value is true if custom_id is specified.

allowlist_url

string

Specify one or more allowlisted URL names (upto 3) where you want to receive delivery reports.
If no URL name(s) are specified here, the system will use your default URL (if one exists).
If no URL name(s) are specified here AND no default URL is set, delivery reports cannot be sent.
Example: ["DynamicWebhookSite", "Mixpanel"]
Example: DynamicWebhookSite

Sample Callback Objects in Request Parameters

1 {
2    "event": "YOUR_EVENT_NAME",
3    "to": { // you channel destination },
4    "data": {  // your template placeholders  },
5    "callback": {
6        "enable":true,
7        "custom_id": "YOUR_CUSTOM_ID_VALUE",
8        "custom1":"3d066514-c55d-48f8-b7ff-3981a43c20d4",
9        "allowlist_url": ["DynamicWebhookSite", "Mixpanel"]
10     }
11 }

Callback Response

The following contains list of default fields which will be sent if the payload for the delivery status callback is not defined.

The Delivery Webhook will be sent using:

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

Sample Webhook Configuration and Response

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

Sample Webhook Configuration

1 {
2   "url": "https://webhook.site/847c54cc-c471-40f4-b793-36c18a",
3   "method": "post",
4   "headers": {
5     "Content-Type": "application/json"
6   },
7   "data": {
8     "recipent": "{{destination}}",
9     "providername": "{{provider}}",
10     "provider_msg_id": "{{provider_msg_id}}",
11     "provider_template_id": "{{provider_template_id}}",
12     "message": "{{message}}",
13     "request_time": "{{senttime}}",
14     "delivery_time": "{{dlrtime}}",
15     "account_name": "{{integration_name}}",
16     "reference_msg_id": "{{custom_id}}",
17     "order_id": "{{custom1}}",
18     "category": "{{custom2}}",
19     "channel": "{{channel}}"
20   }
21 }

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

Sample Callback Response

1 {
2   "custom_id": "YOUR_CUSTOM_ID_VALUE",
3   "msg_id": "FYNO_MSG_ID_UUID",
4   "status": "DELIVERED",
5   "channel": "email",
6   "custom1": "YOUR_CUSTOM1_VALUE",
7   "custom2": "YOUR_CUSTOM2_VALUE",
8   "custom3": "YOUR_CUSTOM_ID_VALUE",
9   "destination": "user1@email.com",
10   "distinct_id": "user1@email.com",
11   "dlrtime": "2023-03-24 10:23:50",
12   "dlrtime_epoch": 1679653430,
13   "event_name": "DELIVERED",
14   "integration_name": "sendgrid",
15   "message": "",
16   "msg_content": "",
17   "params_duration": "",
18   "params_ip": "",
19   "params_recording_link": "",
20   "params_url": "",
21   "params_useragent": "",
22   "provider": "sendgrid",
23   "provider_msg_id": "1234567890",
24   "provider_template_id": "",
25   "request_id": "FYNO_MSG_ID_UUID",
26   "senttime": "2023-03-24 10:23:39",
27   "senttime_epoch": 1679653419,
28   "template": "",
29   "version": "1"
30 }

1	{
2	"event": "YOUR_EVENT_NAME",
3	"to": { // you channel destination },
4	"data": { // your template placeholders },
5	"callback": {
6	"enable":true,
7	"custom_id": "YOUR_CUSTOM_ID_VALUE",
8	"custom1":"3d066514-c55d-48f8-b7ff-3981a43c20d4",
9	"allowlist_url": ["DynamicWebhookSite", "Mixpanel"]
10	}
11	}

1	{
2	"url": "https://webhook.site/847c54cc-c471-40f4-b793-36c18a",
3	"method": "post",
4	"headers": {
5	"Content-Type": "application/json"
6	},
7	"data": {
8	"recipent": "{{destination}}",
9	"providername": "{{provider}}",
10	"provider_msg_id": "{{provider_msg_id}}",
11	"provider_template_id": "{{provider_template_id}}",
12	"message": "{{message}}",
13	"request_time": "{{senttime}}",
14	"delivery_time": "{{dlrtime}}",
15	"account_name": "{{integration_name}}",
16	"reference_msg_id": "{{custom_id}}",
17	"order_id": "{{custom1}}",
18	"category": "{{custom2}}",
19	"channel": "{{channel}}"
20	}
21	}

1	{
2	"custom_id": "YOUR_CUSTOM_ID_VALUE",
3	"msg_id": "FYNO_MSG_ID_UUID",
4	"status": "DELIVERED",
5	"channel": "email",
6	"custom1": "YOUR_CUSTOM1_VALUE",
7	"custom2": "YOUR_CUSTOM2_VALUE",
8	"custom3": "YOUR_CUSTOM_ID_VALUE",
9	"destination": "user1@email.com",
10	"distinct_id": "user1@email.com",
11	"dlrtime": "2023-03-24 10:23:50",
12	"dlrtime_epoch": 1679653430,
13	"event_name": "DELIVERED",
14	"integration_name": "sendgrid",
15	"message": "",
16	"msg_content": "",
17	"params_duration": "",
18	"params_ip": "",
19	"params_recording_link": "",
20	"params_url": "",
21	"params_useragent": "",
22	"provider": "sendgrid",
23	"provider_msg_id": "1234567890",
24	"provider_template_id": "",
25	"request_id": "FYNO_MSG_ID_UUID",
26	"senttime": "2023-03-24 10:23:39",
27	"senttime_epoch": 1679653419,
28	"template": "",
29	"version": "1"
30	}