Tools :: Webhooks – ReachMail

Event webhooks will notify a URL of your choosing via HTTP POST with information about recipient actions as they occur. You can use this data to track unsubscribes, bounces, opens, and clicks. You can read more about the POSTed data below.

Webhook responses will be handled with one of three patterns:

HTTP 200 responses will be considered successful; no retries will occur.
HTTP 406 responses will be considered a permanent reject; no retries will occur.
All other HTTP responses will be considered a temporary failure and will be retired over a period of 24 hours.

Securing Webhooks

To ensure the authenticity of webhook requests, they are signed, and the signature is posted along with other webhook parameters:

Parameter	Type	Description
timestamp	int	Unix timestamp, i.e., a number of seconds passed since Jan. 1, 1970.
token	string	Random string with a length of 50.
signature	string	Hexadecimal string generated by HMAC algorithm.

To verify the authenticity of the message, you must do the following:

Concatenate the timestamp and token values.
Encode the resulting string with the HMAC algorithm using your account id as a key and SHA256 digest mode.
Compare the resulting hexdigest to the signature value.

Webhook Parameters

Parameters common to all webhook posts:

Parameter	Type	Description
email	string	Recipient email address
timestamp	int	Unix timestamp, i.e. seconds passed since Jan. 1, 1970
eventType	string	One of 'Open', 'Click', 'Bounce', or 'Optout'
recipientId	int	The id for the recipient
xCampaign	string	Any x-rm-Campaign header included

Parameters common to all Open, Click, and Optout webhook posts:

Parameters labeled with RM are only available to ReachMail campaigns. EasySMTP campaigns will not supply those values.

Parameter	Type	Description
ipAddress	string	The IP address originating the event.
userAgent	string	The UserAgent string of the client that originated the event.
eventId	string	The id for the event.
listId `RM`	string	The id for the list used in the mailing.
malingId `RM`	string	The id for the mailing from which the event originates.
listName `RM`	string	Name of the list recipient was on.
mailingName `RM`	string	Name of the message this event was responding to.
location	GeoLocation	Geolocation data for the event.
device	Device	Device data for the event.

Optout messages will not have geolocation or device data if they were generated by abuse feedback reports that were received over email channels.

Parameters common to GeoLocation models

Parameter	Type	Description
city	string	City name
countryCode	string	Two character country code
region	string	IP region

Parameters common to Device models

Parameter	Type	Description
clientName	string	The name of the client derived from the HTTP User-Agent header
clientOs	string	The name of the client OS derived from the HTTP User-Agent header
clientType	string	The application type of the client
deviceType	string	The client device type, e.g. mobile, desktop

Parameters common to all Bounce webhook POSTs:

Parameters labeled with RM are only available to ReachMail campaigns. EasySMTP campaigns will not supply those values.

Parameter	Type	Description
bounceCode	string	The evaluated bounce code for the recipient.
reason	string	An interpreted reason for the bounce
smtpStatus	string	The original SMTP status returned by the remote server
smtpDiagnostic	string	The original SMTP diagnostic returned by the remote host
listId `RM`	string	The id for the list used in the mailing.
malingId `RM`	string	The id for the mailing from which the event originates.
listName `RM`	string	Name of the list recipient was on.
mailingName `RM`	string	Name of the message this event was responding to.

Interpreted bounce reasons:

AutoReply
GeneralBounce
ChallengeResponse
HardBounce
MailBlock
NonBounce
SoftBounce
TransientBounce
Unsubscribe
Complaint

Example Request Bodies

All webhook bodies are sent as JSON.

Example open, click, or opt-out body.

{
    timestamp: 1552927113,
    token: "eec6leeraghooNohk8eu4ohshei5IY2biek6aepeixi7maf5be",
    signature: "74e90deabaea9693ca34ea0c59a5d893c2952b3fab82782fce599f9dfb39e494",
    email: "user@domain.com",
    eventType: "Open",
    recipientId: "a8f3ff76-f915-4c8e-a67f-bf3a2179c6a5", 
    xCampaign: "",
    ipAddress: "4.3.2.1",
    userAgent: "Mozilla 5.0",
    eventId: "52e9b845-bb5a-45bb-b8a7-a4946603058b",
    listId: "4f96c5ac-128c-4824-8ffe-8dfa43e3d6eb",
    listName: "My Customers",
    mailingId: "76fb82a5-42a8-4f6d-bf00-d05bac5e9a7d",
    mailingName: "Company Newsletter",
    location: {
       city: "Chicago",
       countryCode: "US",
       region: "IL",
    },
    device: {
        clientName: "Outlook",
        clientOS: "Windows",
        clientType: "Outlook",
        deviceType: "Desktop"
    }
}

Example bounce body.

{
   timestamp: 1552927113,
   token: "eec6leeraghooNohk8eu4ohshei5IY2biek6aepeixi7maf5be",
   signature: "74e90deabaea9693ca34ea0c59a5d893c2952b3fab82782fce599f9dfb39e494",
   email: "user@domain.com",
   eventType: "Open",
   recipientId: "a8f3ff76-f915-4c8e-a67f-bf3a2179c6a5",
   listId: "4f96c5ac-128c-4824-8ffe-8dfa43e3d6eb",
   listName: "My Customers",
   mailingId: "76fb82a5-42a8-4f6d-bf00-d05bac5e9a7d",
   mailingName: "Company Newsletter",
   bounceCode: "HB"
   reason: "HardBounce",
   smtpStatus: "550",
   smtpDiagnostic: "550 invalid user"
}

Comments