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
Comments