Webhook URLs

Version: 1.0 

This feature can only be enabled & configured by a WhatCounts’ employee.  Please contact our support team for assistance.  A future release will allow for configuration of URLs within the UI.  

 

What is a webhook? 

A webhook, also called a callback URL or HTTP push API is a way for an application to provide other applications with real-time information.   

 

How does it work? 

Our webhook feature will make an API call back to a client-defined target each time a (defined) event occurs in the WhatCounts’ platform.  It will notify a URL of the client’s choosing via HTTP with information about those events.   

 

Configuration 

URLs can be configured for these supported event types: 

• Send 
• Open 
• Click 
• Unsub 
• Optout 
• Bounce 
  • A specific URL can be defined for each, with the option to use a different URL for each type.  POST and PUT are supported. HTTP and REST API endpoints are supported. 

 

 

Supported Event Types 

Note: for subscriber-related events, only those that are subscriber-initiated will be supported, regardless of the type of event.  No events triggered by the UI or by an administrator will be supported.   

• One-off Sends (via API only) 
• One-off Opens (Open from One-Off Send (via API only) 
• One-off Clicks (Click from One-Off Send (via API only) 
• Unsubscribes  
• All Hard Bounces  
• All Soft Bounces 
• All Blocked Bounces 
• Opt-Out
• Opt-out Global

Not Supported 

• Bulk Send Events 
• Bulk Open Events 
• Bulk Click Events 
• Custom Fields (not supported in the payload response) 
• Complaints 

Event Definitions 

• One-Off Sends - Send events that originate via the API layer. 
• One-off Opens- Subscriber read or opened the message that was sent via one-off API command. 
• One-off Clicks-Subscriber clicked a link in a message that was sent via one-off API command. 
• Unsubscribe - Users are removed from a list but can re-subscribe in the future. 
• Hard Bounce-Message bounced back as Hard Bounce and opted out. 
• Soft Bounce-Message bounced back as Soft Bounce. 
• Block Bounce-Message bounce back as a Block Bounce.
• Opt-Out- canceling a subscription by clicking an unsubscribe link in an email message. 
• Opt-Out Global- removes subscriptions from all lists. 

Storage Time for Events 

We will store both successful webhook events and failed to call back events for a limited time. Future release(s) will allow for a configurable time period.  

• Successful events -The default storage time is 120 days.   
• Failed events - The default storage time is 120 days. 

Retry Logic 

If an initial attempt fails, we will support a second attempt 1 second later. 

• supported response codes for retry are limited to: 
  • 404: not found
  • 408: timed out
  • 409: conflict, typically means the server cannot handle
  • 429: too many requests

Example Payloads 

• Send Event for non-customer key realm occurs.  
• Payload returned:  {"email":"","first_name":"","realm_name":"","campaign_name":"","list_name":"","subject":"","event_type":"ONE-OFF-SEND","event_date":""} 
• Open Event for non-customer key realm occurs.  
• Payload returned:  {"email":"","first_name":"","realm_name":"","campaign_name":"","list_name":"","subject":"","event_type":"ONE-OFF-OPEN","event_date":""} 
• Click Event for non-customer key realm occurs.  

• Payload returned:  {"email":"","first_name":"","realm_name":"","campaign_name":"","list_name":"","subject":"","event_type":"ONE-OFF-CLICK","event_date":"","url_clicked":""} 
• Unsubscribe Event for non-customer key realm occurs.  
• Payload returned:  {"email":"","first_name":"","realm_name":"","campaign_name":"","list_name":"","event_type":"UNSUB","event_date":""} 
• Hard Bounce Event for non-customer key realm occurs.  
• Payload returned:  {"email":"","first_name":"","realm_name":"","campaign_name":"","list_name":"","event_type":"HARD-BOUNCE","event_date":"","dsn_status_code":"","dsn_action":"","dsn_dialogue":""} 

• Soft Bounce Event for the non-customer key realm occurs.  
• Payload returned:  {"email":"","first_name":"","realm_name":"","campaign_name":"","list_name":"","event_type":"SOFT-BOUNCE","event_date":"","dsn_status_code":"","dsn_action":"","dsn_dialogue":""} 
• Blocked Bounce Event for non-customer key realm occurs.  
• Payload returned:  {"email":"","first_name":"","realm_name":"","campaign_name":"","list_name":"","event_type":"BLOCKED-BOUNCE","event_date":"","dsn_status_code":"","dsn_action":"","dsn_dialogue":""} 
• Opt-Out Event for non-customer key realm occurs.  

• Payload returned:  {"email":"","first_name":"","realm_name":"","campaign_name":"","list_name":"","event_type":"OPT-OUT","event_date":""} 
• Global Opt-Out Event for non-customer key realm occurs.  
• Payload returned:  {"email":"","first_name":"","realm_name":"","campaign_name":"","list_name":"","event_type":"OPT-OUT-GLOBAL","event_date":""}

 

Have more questions? Submit a request 

Webhook Version 1.0 Released in WhatCounts version 16.01.00.