Engagement Metrics Webhook

📘

To utilize this webhook, ensure your endpoint is publicly accessible and capable of handling incoming HTTPS POST requests.

How to configure webhook?

Follow these steps to configure a new webhook for receiving email engagement events:

1. Navigate to API & Webhooks:

   In the dashboard, locate the main navigation menu. Click on API & Webhooks. Under this section, select Webhooks

2. Add New Webhook:

   On the Manage Webhooks page, click the Add New Webhook button

3. Configure Webhook Details:

   Fill in the required information in the Add New Webhook form:

• Webhook name: A descriptive name for the webhook (example: "Email Engagement Listener", "Trigger Email Integration Hook")

• Webhook URL: The publicly accessible URL of your endpoint that will receive the POST requests from our server. This must be an HTTPS URL.

• Secret key: (Optional) The header name for the signature we will send (example: X-Webhook-Signature or a custom header name you prefer). This key, along with the Secret value is used to verify the authenticity of the webhook.

• Secret value: (Optional) The actual secret string to verify the incoming webhook's signature.

  

4. Save and Activate:

   Once all details are entered, Save the webhook. The webhook information should then appear in the Manage Webhooks list with a status, typically Active if the configuration is valid.

📘

The webhook test feature can be used to send a test payload and verify successful receipt during configuration. Webhooks can be edited or deleted from the management page, if needed.

Webhook Request Configuration

• Method: POST
• Webhook URL: The URL configured in your settings to receive webhook events.

All webhook events are sent as POST requests to the endpoint URL provided. Your server must be configured to accept these requests.

Request Headers

The webhook endpoint will receive the following HTTPS headers with each webhook request:

• Content-Type: application/json
• Your_Secret_Key: Secret_Value
  • Your_Secret_Key is the Secret key defined during webhook setup (example: X-Webhook-Signature).
  • Secret_Value is the Secret value defined during webhook setup. This is used to verify the webhook request originated from HealthLink Dimensions Trigger Email platform.

Payload Structure

Each webhook event uses the following JSON structure:

{
    "CampaignID": "string",
    "EventId": "string",
    "EventType": "string",
    "EventTime": "string",
    "EventData": "string",
    "NPI": "string",
    "TemplateId": "string",
    "FromName": "string",
    "Brand": "string",
    "requestId": "string"
}

Engagement Event Types and Sample Payloads

Below are the different types of engagement events that can be received, along with detailed explanations and sample payloads.

1. delivered

   • Description: This event signifies the email has been successfully accepted by the recipient's mail server. It does not guarantee the email has reached the recipient's inbox (it could still be filtered to spam or other folders), but it confirms delivery to the mail server.
   • Sample Payload fordelivered event
   JSON

   {  
     "CampaignID": "1",  
     "EventId": "15",  
     "EventType": "delivered",  
     "EventTime": "2023-06-15T14:59:46",  
     "EventData": "",  
     "NPI": "1053922880",  
     "TemplateId": "1",  
     "FromName": "test from",  
     "Brand": "",  
     "requestId": "B3FB4DC2-8D2B-43ED-9F0E-12E98E07595F"
   }

   
   

2. opened

   • Description: This event is triggered when a recipient opens the email, and the tracking pixel embedded in the email is loaded. Note that open tracking may not be 100% accurate as some email clients block images by default, or users may read emails in plain text. This indicates that the subject line and sender information were compelling enough for the recipient to view the email content. A key metric for engagement.
   • Sample Payload foropenedevent
   JSON

   {  
     "CampaignID": "132",  
     "EventId": "120",  
     "EventType": "opened",  
     "EventTime": "2023-05-29T09:06:33",  
     "EventData": "",  
     "NPI": "1043598477",  
     "TemplateId": "49",  
     "FromName": "test",  
     "Brand": "",  
     "requestId": "B3FB4DC2-8D2B-43ED-9F0E-12E98E07595F"
   }

   
   

3. clicked

   • Description: This event is triggered when a recipient clicks on a tracked link within the email. This measures the effectiveness of the email's call-to-action and content in driving recipients to take the next step. A strong indicator of interest and conversion potential.
   • Sample Payload forclickedevent
   JSON

   {  
     "CampaignID": "132",  
     "EventId": "120",  
     "EventType": "clicked",  
     "EventTime": "2023-05-29T09:06:33",  
     "EventData": "https://example.com/link",  
     "NPI": "1043598477",  
     "TemplateId": "49",  
     "FromName": "test",  
     "Brand": "",  
     "requestId": "B3FB4DC2-8D2B-43ED-9F0E-12E98E07595F"
   }

   
   

4. unsubscribed

   • Description: This event is triggered when a recipient unsubscribes from the mailings. This can happen by clicking an unsubscribe link in the email. This is essential for respecting recipient preferences and complying with anti-spam laws (example: CAN-SPAM, GDPR).
   • Sample Payload for unsubscribedevent
   JSON

   {
     "CampaignID": "132",
     "EventId": "141",
     "EventType": "unsubscribed",
     "EventTime": "2023-05-30T12:27:07",
     "EventData": "https://example.com/unsubscribe",
     "NPI": "1043598477",
     "TemplateId": "49",
     "FromName": "test",
     "Brand": "",  
     "requestId": "B3FB4DC2-8D2B-43ED-9F0E-12E98E07595F"
   }

Webhook Response

Your webhook endpoint must acknowledge receipt of the webhook event by returning an HTTPS 2xx status code (example: 200 OK).

• Successful Acknowledgment: If our server receives a 2xx status code, it considers the event successfully delivered.
• Failure/Retries: If our server receives a non-2xx status code (example: 4xx or 5xx) or if the request times out, we may attempt to resend the event. The retry schedule and number of attempts will be based on our webhook retry policy.

📘

It's recommended to process webhook data asynchronously. Acknowledge receipt immediately (return 200 OK) and then process the payload in a background job or queue. This prevents timeouts and ensures your endpoint remains responsive.