Skip to main content

Webhook URLs

Updated

A webhook, also called a callback URL or HTTP push API, is a way for one application to provide real-time information to another application.   The Webhook feature makes an API call back to a client-defined target each time a specific event occurs in the platform.  It notifies the client via HTTP with information about those events.   

Note: The Webhook feature is only available for transactional emails which are sent via one of the one-off APIs.  It is not available for deployed/marketing campaigns.

Configuration 

Webhook must be enabled and configured by a system administrator.  Please contact our support team for assistance.

Callback URLs can be configured for multiple event types, with the option to use a different URL for each type.  HTTP and REST API endpoints are supported. Each definition requires a URL, Authorization key, and a method (POST or PUT).  A valid HTTP status code is expected on return to determine success or failure.  

Callback URLs can be configured for the following subscriber initiated event types: 

  • Send 
    • One-off message Send events triggered via API only
  • Open 
    • Subscriber read or opened the message sent via one-off API command. 
  • Click 
    • Subscriber clicked a link in the message sent via one-off API command.
  • Unsubscribe 
  • Opt Out
    • List Opt Out
    • Global Opt Out
  • Bounce (Subscriber initiated and automated mail system generated)  
    • All Hard Bounces
    • All Soft Bounces 
    • All Blocked Bounces 
    • Removal Requests via Reply

Events triggered by the UI or by an administrator are not supported.   Events generated from the following sources do not generate Webhook callbacks:

  • Bulk Events (send, open, click), such as those from campaigns deployed through the UI
  • Custom Fields are not supported in the payload response
  • Complaints Bounces

Storage Time for Events 

Both successful and failed callback events are stored for a limited time.

  • Successful events: 120 days
  • Failed events: 120 days

Success Status Codes

To report a value success, return a 2xx status code, such as:

  • 200 OK
  • 202 Accepted
  • 204 No Content

Failure Status Codes for Retry

If an initial attempt fails, a second attempt occurs second later.  Supported response codes for retry are limited to the following: 

  • 404 Not Found
  • 408 Request Timeout
  • 409 Conflict 
  • 429 Too Many Requests

All other failure codes will report as a Failure.

Example Payloads 

  • Send Event for non-customer key realm occurs.  Payload returned:  {"email":"","firstName":"","realmName":"","campaignName":"","listName":"","subject":"","eventType":"SEND","event_date":""} 
  • Open Event for non-customer key realm occurs. Payload returned:  {"email":"","firstName":"","realmName":"","campaignName":"","listName":"","subject":"","eventType":"OPEN","eventDate":""} 
  • Click Event for non-customer key realm occurs. Payload returned:  {"email":"","firstName":"","realmName":"","campaignName":"","listName":"","subject":"","eventType":"CLICK","eventDate":"","urlClicked":""} 
  • Unsubscribe Event for non-customer key realm occurs. Payload returned:  {"email":"","firstName":"","realmName":"","campaignName":"","listName":"","eventType":"UNSUB","eventDate":""} 
  • Hard Bounce Event for non-customer key realm occurs. Payload returned:  {"email":"","firstName":"","realmName":"","campaignName":"","listName":"","eventType":"HARD BOUNCE","eventDate":"","dsnStatusCode":"","dsnAction":"","dsnDialogue":""}
  • Soft Bounce Event for the non-customer key realm occurs.  Payload returned:  {"email":"","firstName":"","realmName":"","campaignName":"","listName":"","eventType":"SOFT BOUNCE","eventDate":"","dsnStatusCode":"","dsnAction":"","dsnDialogue":""} 
  • Blocked Bounce Event for non-customer key realm occurs.  Payload returned:  {"email":"","firstName":"","realmName":"","campaignName":"","listName":"","eventType":"BLOCKED BOUNCE","eventDate":"","dsnStatusCode":"","dsnAction":"","dsnDialogue":""} 
  • Opt-Out Event for non-customer key realm occurs.  Payload returned:  {"email":"","firstName":"","realmName":"","campaignName":"","listName":"","eventType":"UNSUB","eventDate":""} 
  • Global Opt-Out Event for non-customer key realm occurs. Payload returned:  {"email":"","firstName":"","realmName":"","campaignName":"","listName":"","eventType":"OPTOUT GLOBAL","eventDate":""}
  •  

 

Webhook Version 1.0 Released in WhatCounts version 16.01.00.

 

 

 

Related articles