The Webhook plugin can be configured against your Customer Space to send raw recipient email activity to a URL endpoint in your system in near-real-time. It is typically used to add logs of recipient activity into a third-party CRM system.
Maxemail will send the raw event data to the URL provided by the client. Although it's possible to configure which events are sent, the data that is included cannot be adjusted.
URL
You must provide Xtremepush with a URL to which Maxemail will send the data. Only one URL can be configured per Customer Space. The URL must be secure (ie. HTTPS) as the events contain protected recipient data.
Success response
Your platform must respond with a
200 OKHTTP header. When Maxemail doesn't receive a200 OKheader, the event will be attempted again with an increasing delay of up to 3 hours, for a maximum of 3 days. At this point, the Webhook job will be discarded.
Agency spaces
For clients with agency spaces, it's possible for the Webhook URL to be configured at the parent agency-level, so that all of the customer spaces send events to the same URL. This may provide simpler configuration, and save having to ask for Webhooks to be enabled when new customer spaces are added.
Events
The following events are available, across Email Campaigns, Triggered Emails and Transactional SMTP:
sendbounceopenclickunsubscribetrack(ROI, not available for Transactional SMTP)complete(ROI, not available for Transactional SMTP)delete(Fired immediately before the Recipient is permanently deleted)
By default all event types are sent, but it's possible to configure the plugin to send a subset of these events.
Requests are made to the Webhook URL using the POST method, with the request body containing JSON-encoded array of multiple events. Each nested event object has an event key containing the event name as a string, and a data key containing an object for all the event properties.
The properties available within the event data vary by event type, however recipient_id, email_address and timestamp would be expected as a minimum. See the examples for more details about what properties are included.
Legacy format
Clients using the legacy Webhook format will receive events as GET requests with a single event with event and data parameters. To upgrade to the current version, please speak to the Support Team.
Identifiers
The IDs provided in events are scoped to a single customer space. If you are receiving events for multiple spaces, it's important to recognise that, for example, recipient 123 in one customer is not the same as recipient 123 in another customer.
Customer IDs (and corresponding names) are provided to help differentiate the source of the events, and should be used in combination with relevant IDs to identify unique recipients, emails, etc.
Examples
Email Campaigns & Triggered Emails
{
"event": "send",
"data": {
"email_id": 123,
"subject_line": "Email Subject 123",
"description": "Preview text",
"from_address": "[email protected]",
"from_address_alias": "From Name",
"reply_to": "[email protected]",
"reply_to_alias": "Reply Name",
"use_opens": 1,
"use_click_thrus": 1,
"use_roi": 0,
"list_total": 4598,
"total_sent": 4598,
"scheduled_ts": "2016-12-07 11:30",
"start_ts": "2016-12-07 11:31",
"finish_ts": "2016-12-07 11:32",
"customer_id": 111,
"customer_name": "Customer Name",
"recipient_id": 12358,
"email_address": "[email protected]",
"timestamp": 1480688680
}
}
{
"event": "send",
"data": {
"email_id": 123,
"subject_line": "Email Subject 123",
"description": "Preview text",
"from_address": "[email protected]",
"from_address_alias": "From Name",
"reply_to": "[email protected]",
"reply_to_alias": "Reply Name",
"use_opens": 1,
"use_click_thrus": 1,
"use_roi": 0,
"list_total": null,
"total_sent": 4598,
"customer_id": 111,
"customer_name": "Customer Name",
"recipient_id": 12358,
"email_address": "[email protected]",
"timestamp": 1480688680
}
}
{
"event": "bounce",
"data": {
"email_id": 123,
"customer_id": 111,
"customer_name": "Customer Name",
"recipient_id": 12358,
"email_address": "[email protected]",
"timestamp": 1480688680,
"hard_bounce": true,
"bounce_code": 500,
"bounce_reason": "0176 other \"Delivery to the following recipients failed.\r\n\r\n [email protected]\"",
"bounce_category": "other"
}
}
{
"event": "open",
"data": {
"email_id": 123,
"customer_id": 111,
"customer_name": "Customer Name",
"recipient_id": 12358,
"email_address": "[email protected]",
"timestamp": 1480688680,
"client_name": "AppleMail",
"device_name": "Mac 10.13"
}
}
{
"event": "click",
"data": {
"email_id": 123,
"customer_id": 111,
"customer_name": "Customer Name",
"recipient_id": 12358,
"email_address": "[email protected]",
"timestamp": 1480688680,
"device_name": "Mac 10.13",
"link_id": 15063,
"link_url": "https:\/\/www.example.com\/?key1=value1&key2=value2"
}
}
{
"event": "unsubscribe",
"data": {
"email_id": 123,
"customer_id": 111,
"customer_name": "Customer Name",
"recipient_id": 12358,
"email_address": "[email protected]",
"timestamp": 1480688680,
"unsubscribe_method": "feedback"
}
}
{
"event": "unsubscribe",
"data": {
"email_id": 123,
"customer_id": 111,
"customer_name": "Customer Name",
"recipient_id": 12358,
"email_address": "[email protected]",
"timestamp": 1480688680,
"device_name": "Mac 10.13",
"unsubscribe_method": "form",
"link_id": 15067,
"link_type": "local"
}
}
{
"event": "track",
"data": {
"email_id": 123,
"customer_id": 111,
"customer_name": "Customer Name",
"recipient_id": 12358,
"email_address": "[email protected]",
"timestamp": 1480688680,
"revenue": 20054
}
}
{
"event": "complete",
"data": {
"email_id": 123,
"customer_id": 111,
"customer_name": "Customer Name",
"recipient_id": 12358,
"email_address": "[email protected]",
"timestamp": 1480688680,
"revenue": 20054,
"reference": "ORD12345"
}
}
Transactional Emails
{
"event": "send",
"data": {
"customer_id": 111,
"customer_name": "Customer Name",
"recipient_id": 12358,
"email_address": "[email protected]",
"timestamp": 1480688680,
"trx_id": "8d8a32c9223dee3b654e9e890307f7e3",
"message_id": "[email protected]",
"from_address": "[email protected]",
"subject_line": "Email Subject 123",
"sent_ts": "2016-12-05 11:24:56",
"bcc_address": "[email protected]",
"hasHtml": true,
"hasText": true,
"attachments": 0,
"checkUnsubs": false,
"ignoreBounces": false,
"trackOpens": true,
"trackClicks": true,
"tags": [
"taga",
"tagb"
]
}
}
{
"event": "bounce",
"data": {
"customer_id": 111,
"customer_name": "Customer Name",
"recipient_id": 12358,
"email_address": "[email protected]",
"timestamp": 1480688680,
"trx_id": "8d8a32c9223dee3b654e9e890307f7e3",
"message_id": "[email protected]",
"hard_bounce": true,
"bounce_reason": "0176 other \"Delivery to the following recipients failed.\r\n\r\n [email protected]\""
}
}
{
"event": "open",
"data": {
"customer_id": 111,
"customer_name": "Customer Name",
"recipient_id": 12358,
"email_address": "[email protected]",
"timestamp": 1480688680,
"trx_id": "8d8a32c9223dee3b654e9e890307f7e3",
"message_id": "[email protected]",
"client_name": "AppleMail",
"device_name": "Mac 10.13"
}
}
{
"event": "click",
"data": {
"customer_id": 111,
"customer_name": "Customer Name",
"recipient_id": 12358,
"email_address": "[email protected]",
"timestamp": 1480688680,
"trx_id": "8d8a32c9223dee3b654e9e890307f7e3",
"message_id": "[email protected]",
"device_name": "Mac 10.13",
"link_id": 15063,
"link_url": "https:\/\/www.example.com\/?key1=value1&key2=value2"
}
}
{
"event": "unsubscribe",
"data": {
"customer_id": 111,
"customer_name": "Customer Name",
"recipient_id": 12358,
"email_address": "[email protected]",
"timestamp": 1480688680,
"trx_id": "8d8a32c9223dee3b654e9e890307f7e3",
"message_id": "[email protected]",
"unsubscribe_method": "feedback"
}
}
Recipient
{
"event": "delete",
"data": {
"customer_id": 111,
"customer_name": "Customer Name",
"recipient_id": 12358,
"email_address": "[email protected]",
"timestamp": 1480688680
}
}