How to receive Delivery Reports

To receive delivery reports in your system, you need to follow the below steps

  1. Add an Allowlist URL/SQS and get it verified.
  2. Configure the delivery data points you want to receive
  3. Configure the Allowlist URL/SQS to receive delivery report
    • Through API
    • Through Campaign
    • Through Workflow

1. Add an Allowlist URL and get it verified

Allowlist (also commonly called as Webhooks) is a list of URLs or SQS that you would need to add to the Fyno platform and verify before you use it on the application and in your workflows.

You need to add Allowlist URL or SQS in 2 cases.

  • When you want to receive a delivery report from Fyno to your system
  • When you want to call your API from Fyno’s Workflow

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/SQS and thus help avoid unnecessary security hassles.

Types of Allowlist

You can add Allowlists as:

  1. URL
  2. SQS

2. Configure the delivery data points you want to receive

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 any verified endpoint, 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.

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.

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

If you didn’t any parameters in the payload, Fyno will send the below default parameters.

Default Parameters

Parameter NameType & Value
custom_idString or Number; an alpha-numeric or 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

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 or Number; an alpha-numeric or 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; destinations like email, mobile no sent during submission request.
example : abc@gmail.com, 919876543210
distinct_idString; It holds the distinct_id of the user, if specified in the request
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
senttime_epochString; Submission time of the request in epoch format (Unix time)
dlrtimeString; The time when the delivery report status was received, YYYY-MM-DD HH:mm:ss UTC
dlrtime_epochString; The time when the delivery report status was received in epoch format (Unix time)
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
provider_msg_idString; the msg ID (if available) of the provider via which the notification was sent
provider_template_idString; 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_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
msg_contentJSON 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.
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

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.

3. Configure the Allowlist URL to receive delivery report

You can configure delivery callback when you are triggering through

  • API
  • Campaign
  • Workflow

How to configure delivery callback through API

When you are triggering a notification event using API, you need to pass additional parameters in the payload

Sample Notification Event API with delivery callback details

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 "custom_id": "YOUR_CUSTOM_ID_VALUE",
7 "custom1":"3d066514-c55d-48f8-b7ff",
8 "custom2":"3d066514-c55d-48f8-b7ff-3981a43c20d4",
9 "allowlist_url": ["DynamicWebhookSite", "Mixpanel"],
10 "enable":true
11 }
12}
custom_id
stringRequired
  • Unique identifier of your notification
  • Length: 200 characters if string
  • Length: 20 digits if numeric
custom1
string
  • Additional information to tag your notification
  • Length: 50 characters
  • Example: order-id
custom2
string
  • Additional information to tag your notification
  • Length: 50 characters
  • Example: category
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 (up to 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

How to configure delivery callback in Campaign

To enable receiving delivery reports from Fyno, select the checkbox ‘Receive delivery report from Fyno to my allowlisted endpoint(s)’. This enables the callbacks for the channels and essentially sends back the delivery updates about each notification triggered. On checking this box, 3 additional placeholder details will need to be configured.

Allowlisted Endpoints
string
  • Specify one or more allowlisted URL names (up to 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
Custom ID
stringRequired
  • Unique identifier of your notification
  • Length: 200 characters if string
  • Length: 20 digits if numeric
Custom Value 1
string
  • Additional information to tag your notification
  • Length: 50 characters
  • Example: campaign-name
Custom Value 2
string
  • Additional information to tag your notification
  • Length: 50 characters
  • Example: category

More values can be added in the callback. For a list of additional available values, please see: Callback Response

How to configure delivery callback in Workflow

1To configure callbacks to receive delivery reports, click the Settings icon while configuring notification event within a workflow as shown below.
2It opens the page as shown below. Select the ‘Do you want to receive a delivery report?’ checkbox.
3

This option allows you to receive Delivery reports of each notification triggered in any URL you have allowlisted in Fyno. It can be done in 2 ways.

  1. From Allowlist - Selecting Delivery Report Endpoint(s) from Verified Allowlist URLs (Maximum 3 can be selected).
  2. Custom - Selecting Delivery Report Endpoint from payload or a simplified custom variable. (Only 1 can be selected).

Once the Delivery Endpoint URL(s) is selected, 3 additional placeholder details need to be configured.

Custom ID
stringRequired
  • Unique identifier of your notification
  • Length: 200 characters if string
  • Length: 20 digits if numeric
Custom Field 1
string
  • Additional information to tag your notification
  • Length: 50 characters
  • Example: order-id
Custom Field 2
string
  • Additional information to tag your notification
  • Length: 50 characters
  • Example: category

More values can be added in the callback. For a list of additional available values, click here.

Callback Response

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 "msg_id": "FYNO_MSG_ID_UUID",
3 "status": "DELIVERED",
4 "custom_id": "YOUR_CUSTOM_ID_VALUE",
5 "recipent": "user1@email.com",
6 "providername": "sendgrid",
7 "provider_msg_id": "1234567890",
8 "provider_template_id": "",
9 "message": "",
10 "requesttime": "2023-03-24 10:23:39",
11 "deliverytime": "2023-03-24 10:23:50",
12 "account_name": "EmailProduction",
13 "reference_msg_id": "YOUR_CUSTOM_ID_VALUE",
14 "order_id": "YOUR_CUSTOM1_VALUE",
15 "category": "YOUR_CUSTOM2_VALUE",
16 "channel": "email"
17}