This is an old revision of the document!

Contact Unsubscribe Webhook

When a Contact unsubscribes, you can have Sentori pass this information on to an external system, such as your CRM system, to keep everything in sync.

To use this feature, set the Contact Unsubscribe Webhook for your account by signing in to Sentori then going to the Settings menu and choosing API.

Request

This is how Sentori structures its request to your external system when a Contact unsubscribes:

HTTP Method: POST

HEADERS

Content-Typeapplication/json

BODY

AccountExternalIDThe External ID of the Account the Contact has unsubscribed from.
EmailAddressThe email address of the Contact that has unsubscribed.
TypeThe string “unsubscribe”.
DateThe date and time when the unsubscribe occurred. Formatted to ISO 8601, e.g. “2016-02-01T14:12:59.1230000Z”
vhashA hashed value used to confirm it's a genuine notification from Sentori.
DescriptionA human-readable message containing the other values.

Example Request from Sentori

POST [your webhook url] HTTP/1.1
Content-Type: application/json
User-Agent: Sentori API
Content-Length: 314

{
    "AccountExternalID":"1234ABCD",
    "EmailAddress":"user@example.com",
    "Type":"unsubscribe",
    "Date":"2016-02-01T14:12:59.1230000Z",
    "vhash":"F88EA6387F4CF9F258521444C34FEB526DF66A55",
    "Description":"\"user@example.com\" logged \"unsubscribe\" Event at \"Mon 01 Feb 2016 14:12 UTC\"."
}

Confirm the Request is Genuine

To confirm the request isn't from another system impersonating Sentori, perform the following operation.

  1. Concatenate the AccountExternalID, EmailAddress, Type, Date values from the request (so exclude Description and vhash) and your API Key
  2. Convert the result into bytes
  3. Get the SHA1 hash of those bytes and remove any hyphen characters

If the result matches the vhash value in the request, it's genuine.



Here's the example above being checked using C# code:

The API Key of this Sentori Account is “20011111-1111-1111-1111-111111111200”. 

string values = "1234ABCD" + "user@example.com" + "unsubscribe" + "2016-02-01T14:12:59.1230000Z" + "20011111-1111-1111-1111-111111111200";
byte[] bytes = System.Text.Encoding.Default.GetBytes(values);
System.Security.Cryptography.SHA1Managed sha1 = new System.Security.Cryptography.SHA1Managed();

string checkHash = BitConverter.ToString(sha1.ComputeHash(bytes));
checkHash = checkHash.Replace("-", string.Empty);

// Output is "true" if genuine, "false" if not.
Console.WriteLine("Is genuine? " + ("F88EA6387F4CF9F258521444C34FEB526DF66A55" == checkHash));



Contact Bad Email Webhook

When a Contact is marked as having a Bad Email Address (as a result of Sentori receiving one or more bounce messages depending on the type of bounce), you can have Sentori pass this information on to an external system, such as your CRM system, to keep everything in sync.

To use this feature, set the Contact Bad Email Webhook for your account by signing in to Sentori then going to the Settings menu and choosing API.

Contacts are marked as “Bad” when their “Bad Email Address” boolean Field is set to “True” (or “Yes”). Sentori excludes those Contacts from sends.

Request

This is how Sentori structures its request to your external system when a Contact is marked as Bad:

HTTP Method: POST

HEADERS

Content-Typeapplication/json

BODY

AccountExternalIDThe External ID of the Account the Contact was marked Bad in.
EmailAddressThe email address of the Contact that has been marked as Bad.
TypeThe string “set”, indicating the “Bad Email Address” flag on the Contact has been “set”.
LatestBounceMessageThe most recent bounce message received by Sentori that has resulted in the Contact being marked as Bad.
DateThe date and time when the last bounce message was received by Sentori which resulted in the Contact being marked as Bad. Formatted to ISO 8601, e.g. “2016-02-01T14:12:59.1230000Z”
vhashA hashed value used to confirm it's a genuine notification from Sentori.
DescriptionA human-readable message containing the other values.

Example Request from Sentori

POST [your webhook url] HTTP/1.1
Content-Type: application/json
User-Agent: Sentori API
Content-Length: 455

{
    "AccountExternalID":"1234ABCD",
    "EmailAddress":"user@example.com",
    "Type":"set",
    "LatestBounceMessage":"550 Invalid Recipient user@example.com",
    "Date":"2016-02-01T14:12:59.1230000Z",
    "vhash":"8E1CBD29F97D7725B330AFCD02913226B2D8EA5B",
    "Description":"\"user@example.com\" logged \"set\" Event for Bad Email Address at \"Mon 01 Feb 2016 14:12 UTC\".  Latest Bounce Reason: \"550 Invalid Recipient user@example.com\""
}

Confirm the Request is Genuine

To confirm the request isn't from another system impersonating Sentori, perform the following operation.

  1. Concatenate the AccountExternalID, EmailAddress, Type, LatestBounceMessage, Date values from the request (so exclude Description and vhash) and your API Key
  2. Convert the result into bytes
  3. Get the SHA1 hash of those bytes and remove any hyphen characters

If the result matches the vhash value in the request, it's genuine.



Here's the example above being checked using C# code:

The API Key of this Sentori Account is “20011111-1111-1111-1111-111111111200”. 

string values = "1234ABCD" + "user@example.com" + "unsubscribe" + "2016-02-01T14:12:59.1230000Z" + "20011111-1111-1111-1111-111111111200";
byte[] bytes = System.Text.Encoding.Default.GetBytes(values);
System.Security.Cryptography.SHA1Managed sha1 = new System.Security.Cryptography.SHA1Managed();

string checkHash = BitConverter.ToString(sha1.ComputeHash(bytes));
checkHash = checkHash.Replace("-", string.Empty);

// Output is "true" if genuine, "false" if not.
Console.WriteLine("Is genuine? " + ("8E1CBD29F97D7725B330AFCD02913226B2D8EA5B" == checkHash));