Follow

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. 

 

blobid0.gif

 

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 

 

 

 

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk