The Webhook feature will push content extracted from DSAR to a webhook listener on your server. Each time a task successfully responds to an opt-out request it will send a JSON object of the message content to your server. A sample JSON object is shown below.
Example Webhook JSON:
{
"data": [
{"Name":"Mr President","Email":"president@whitehouse.com,"Address":"1600 Pennsylvania Ave., NW Washington, DC 20500"},
{"Name":"Example Name","Email":"example@gmail.com","Address":"111 2nd Ave, New Town, NJ, USA."},
{"Name":"John Doe","Email":"john.doe@gmail.com","Address":"123 1st Street, Any town, CA, 94121, USA."}
],
"tags": ["Name","Email","Address"],
"task_name": "Test name",
"task_email": "info@gmail.com",
"type":"mail.task.compliance.save"
}
Included in the JSON payload are the tags, the task name, the task email and the task type. This allows your develoment team to create logic to process content from different tasks differently, if required.
Step 1. Getting Started. To begin with you will need to enable API access on SimpleOptOutCompliance.com. You can find out how to do this here.
Step 2. Add Webhook. Select the Webhook menu item on the left, as shown below. This will bring up a list of Webhooks that have already been added to your account. To get started, click the Add Endpoint button.
Step 3. Enter Webhook Information. You will now need to fill in details about the webhook.
Name: what you want to call it.
Endpoint url: where will the webhook be pushing data to.
Tasks: which tasks will trigger the webhook to push data. This is a multi select control, so one webhook can serve multiple tasks.
Once these are completed, click Save in the top right hand corner of the form.
Step 4. Get Customer Secret. Once the Webhook is created, the app will create the Endpoint secret. This is passed each time the webhook is triggered. The Endpoint secret needs to be added to the Webhook listener on your site to allow your application to authenticate the message sender and receive JSON objects passed by this webhook.
Step 4. Setting Up A Webhook Listener. This code will vary dependent on the language used to developed your site. Below are a few examples:
Example PHP Web App:
<?php
header("Content-Type: application/json; charset=UTF-8");
$header_name ="HTTP_SIMPLEOPTOUTSITE_SECRET";
// Change endpoint secret if you implement these methods.
$endpoint_secret ="";
if(!isset($_SERVER[$header_name])){
http_response_code(400);
die("Header missing !");
}
if ($_SERVER[$header_name]!==$endpoint_secret){
http_response_code(400);
die("Endpoint secret invalid !");
}
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
http_response_code(405);
die("Method not allowed");
}
$entityBody = trim(file_get_contents('php://input'));
$json = json_decode($entityBody,true);
process_event($json);
die();
function process_event($json): void
{
switch ($json['type']){
case "mail.task.compliance.save":
mail_task_compliance_save_event_handler($json['data'],$json['tags'],$json['task_email'],$json['task_name']);
echo "Success !";
http_response_code(200);
break;
}
}
function mail_task_compliance_save_event_handler($data,$tags,$task_email,$task_name): void
{
//Change to your DB name
$conn = new mysqli("localhost", "user_name", "password", "db_name");
// Check connection
if($conn === false){
die("ERROR: Could not connect. ". mysqli_connect_error());
}
//for each tag - get value and insert new entry into temporary_table
for ($i = 0; $i < count($data); $i++) {
$dataArray = $data[$i];
foreach ($tags as $key) {
//Change fields to match field names in your DB table
$sql = "INSERT INTO temporary_table (tag_name, tag_content,task_name) VALUES ('$key','$dataArray[$key]','$task_name')";
if(mysqli_query($conn, $sql)){
//All good
} else {
echo "ERROR: $sql. ". mysqli_error($conn);
mysqli_close($conn);
break;
}
}
}
}
?>
Step 5. Testing Your Webhook. We set up an example endpoint for a Webhook to send data to. You can set this up by adding the endpoint url https://webhook.simpleoptoutcompliance.com/listener.php to a new Webhook. Once the Webhook is created, copy the Endpoint Secret and then go to the testing site: https://webhook.simpleoptoutcompliance.com/.
Paste the secret in to the first text box Add Webhook Secret and click 'Insert'. Now, send some test emails to an email address a task is monitoring. Once you receive responses from the task you can then paste the secret into the second text box Check Entries and click 'Retrieve' to display the data the Webhook sends to an endpoint. This will display the last 10 records in a table for a few seconds before refreshing the page.
See this FAQ section for code snippets written in Python, Node.js, Ruby and Go. In the meantime, email support@simpleoptoutcompliance.com to find out more about using webhooks.