Differences

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

--- api-webhooks [2017/01/18 14:15]
ben [Mailig List Subscribe Webhook]
+++ api-webhooks [2017/01/18 14:25]
ben [Confirm the Request is Genuine]
@@ Line 188: / Line 188: @@
   "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>
+===== Mailig 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>
+\\
+\\
 ==== Confirm the Request is Genuine ====