Differences

This shows you the differences between two versions of the page.

--- api-webhooks [2016/10/28 15:32]
ben [Interactions Webhook]
+++ api-webhooks [2017/07/26 08:24] (current)
@@ Line 148: / Line 148: @@
 \\
 \\
+===== Mailing List Subscribe Webhook =====
+Sentori calls this Webhook when a Contact is added to a Mailing List, whether by a Contact performing an action or a User through Sentori's interface.
+Note: This Webhook is //not// called when uploading Contacts.
+==== Request ====
+This is how Sentori structures its request to your external system when a Contact is added to a Mailing List:
+===HTTP Method: POST===
+===HEADERS===
+|Content-Type|application/json|
+===BODY===
+|AccountExternalID|The External ID of the Account this relates to.|
+|EmailAddress|The email address of the Contact that has subscribed.|
+|MailingListExternalID|The External ID of the Mailing List subscribed to.|
+|Type|The string "subscribe".|
+|Date|The date and time when the operation occurred.  Formatted to ISO 8601, e.g. "2016-02-01T14:12:59.1230000Z"|
+|vhash|A hashed value used to confirm it's a genuine notification from Sentori.|
+|Description|A human-readable message containing the other values.|
+==== Example Request from Sentori ====
+<code>
+POST [your webhook url] HTTP/1.1
+Content-Type: application/json
+User-Agent: Sentori API
+Content-Length: 410
+{
+  "AccountExternalID" : "1234ABCD",
+  "EmailAddress" : "user@example.com",
+  "MailingListExternalID" : "ABCD1234",
+  "Type" : "subscribe",
+  "Date" : "2016-10-28T14:59:43.6889402Z",
+  "vhash" : "EC0A73A0091CF860DCBD0B572CD8042A9B702D7B",
+  "Description" : "\"user@example.com\" logged \"subscribe\" Event for Mailing List \"Members Offers\" (ExternalID: ABCD1234) at \"Fri 28 Oct 2016 14:59 UTC\"."
+}
+</code>
+==== Confirm the Request is Genuine ====
+To confirm the request isn't from another system impersonating Sentori, perform the following operation.
+  - Concatenate the //AccountExternalID//, //EmailAddress//, //MailingListExternalID//, //Type//, //Date// values from the request (so exclude //Description// and //vhash//) and your //API Key//
+  - Convert the result into bytes
+  - 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".
+<code>
+string values = "1234ABCD" + "user@example.com" + "ABCD1234" + "subscribe" + "2016-10-28T14:59:43.6889402Z" + "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? " + ("0321B442144F3EF8663EF47D738E2EDEDEBDF73F" == checkHash));
+</code>
+\\
+\\
+===== Mailing List Unsubscribe Webhook =====
+Sentori calls this Webhook when a Contact is removed from a Mailing List, whether by a Contact performing an action (including Unsubscribing from the Account) or a User through Sentori's interface.
+Note: This Webhook is //not// called when uploading a Suppression List.
+==== Request ====
+This is how Sentori structures its request to your external system when a Contact is removed from a Mailing List:
+===HTTP Method: POST===
+===HEADERS===
+|Content-Type|application/json|
+===BODY===
+|AccountExternalID|The External ID of the Account this relates to.|
+|EmailAddress|The email address of the Contact that has unsubscribed.|
+|MailingListExternalID|The External ID of the Mailing List unsubscribed from.|
+|Type|The string "unsubscribe".|
+|Date|The date and time when the operation occurred.  Formatted to ISO 8601, e.g. "2016-02-01T14:12:59.1230000Z"|
+|vhash|A hashed value used to confirm it's a genuine notification from Sentori.|
+|Description|A human-readable message containing the other values.|
+==== Example Request from Sentori ====
+<code>
+POST [your webhook url] HTTP/1.1
+Content-Type: application/json
+User-Agent: Sentori API
+Content-Length: 414
+{
+  "AccountExternalID" : "1234ABCD",
+  "EmailAddress" : "user@example.com",
+  "MailingListExternalID" : "ABCD1234",
+  "Type" : "unsubscribe",
+  "Date" : "2016-10-28T14:59:43.6889402Z",
+  "vhash" : "EC0A73A0091CF860DCBD0B572CD8042A9B702D7B",
+  "Description" : "\"user@example.com\" logged \"unsubscribe\" Event for Mailing List \"Members Offers\" (ExternalID: ABCD1234) at \"Fri 28 Oct 2016 14:59 UTC\"."
+}
+</code>
+==== Confirm the Request is Genuine ====
+To confirm the request isn't from another system impersonating Sentori, perform the following operation.
+  - Concatenate the //AccountExternalID//, //EmailAddress//, //MailingListExternalID//, //Type//, //Date// values from the request (so exclude //Description// and //vhash//) and your //API Key//
+  - Convert the result into bytes
+  - 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".
+<code>
+string values = "1234ABCD" + "user@example.com" + "ABCD1234" + "unsubscribe" + "2016-10-28T14:59:43.6889402Z" + "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? " + ("6769BC487AB5F54FE2AA5858FB6260FBFB0DD7A2" == checkHash));
+</code>
+\\
+\\
 ===== Email Bounce Webhook =====
@@ Line 235: / Line 380: @@
 Sentori calls this Webhook when a Contact first performs certain interactions with an Email (e.g. opens the email or clicks a link) you can have Sentori pass this information on to an external system that may perform additional tasks.
-To use this feature, set the Interactions Webhook on an Email by clicking the Email Tools menu button and selecting Interactions Webhook.
+At present, this is limited to External Link Clicks only.
-You'll be presented with a popup that allows you to enter a URL to the external system, as well tickboxes for each interaction that Sentori currently supports.  Initially this is limited to External Link Clicks, but further options will be added in future.
-NOTE: Sentori will only call your webhook URL the first time each of your Contacts performs one of your selected interactions, not every time.  So (once we've implemented this for Opens) if a Contact Opens your email 5 times, it would only be called for the first Open.  Each link is considered a separate interaction so it would be called the first time a Contact clicks each link.
+NOTE: Sentori will only call your webhook URL the first time each of your Contacts performs one of your selected interactions, not every time.  So (once we've implemented this webhook for Opens) if a Contact Opens your email 5 times, it would only be called for the first Open.  Each link is considered a separate interaction so it would be called the first time a Contact clicks each link in an Email.