Webhooks allow your server to be notified about activities with your contact lists. You can configure what type of event updates you would like to receive at your account's settings page.
The url on your server should respond to the HTTP HEAD request with a HTTP status code 200 to indicate that data has been successfully received. In case of failure we will retry sending Webhook again at increasing intervals up to 3 hours.
A Webhook is sent as a JSON document with HTTP POST request to your specified url. Each JSON document follows the following format:
{
"timestamp": 1422006776,
"events": [
{
"type": "contact.subscribe",
"data": { ... }
}
]
}
You can choose what event types (listed and described below) and what event sources (subscriber, account admin, API) you are intereseted in.
This event is triggered only when contact is opted-in - either by confirmation link or at import process.
{
"hook": "contact.subscribe",
"timestamp": 1422006776,
"data": [
{
"contact": "58eacf62",
"list": "7f38c166",
"email": "webhook.contact@example.com",
"email_type": "html",
"fields": {
"EMAIL": "webhook.contact@example.com",
"FNAME": "Webhook",
"LNAME": "Contact"
},
"subscribe_ip": "17.178.96.59",
"subscribe_ts": 1421942911,
"confirm_ip": "17.178.96.59",
"confirm_ts": 1421942977,
"optin_ip": "17.178.96.59",
"optin_ts": 1421942977
}
]
}
{
"hook": "contact.unsubscribe",
"timestamp": 1422006777,
"data": [
{
"contact": "58eacf62",
"list": "7f38c166",
"email": "webhook.contact@example.com",
"email_type": "html",
"fields": {
"EMAIL": "webhook.contact@example.com",
"FNAME": "Webhook",
"LNAME": "Contact"
},
"subscribe_ip": "17.178.96.59",
"subscribe_ts": 1421942911,
"confirm_ip": "17.178.96.59",
"confirm_ts": 1421942977,
"optin_ip": "17.178.96.59",
"optin_ts": 1421942977,
"unsubscribe_ip": "17.142.160.59",
"unsubscribe_ts": 1421943100
}
]
}
{
"hook": "contact.update",
"timestamp": 1422006774,
"data": [
{
"contact": "58eacf62",
"list": "7f38c166",
"email": "webhook.contact@example.com",
"email_type": "html",
"fields": {
"EMAIL": "webhook.contact@example.com",
"FNAME": "Webhook",
"LNAME": "Contact"
},
"subscribe_ip": "17.178.96.59",
"subscribe_ts": 1421942911,
"confirm_ip": "17.178.96.59",
"confirm_ts": 1421942977,
"optin_ip": "17.178.96.59",
"optin_ts": 1421942977
}
]
}
{
"hook": "email.change",
"timestamp": 1422006773,
"data": [
{
"contact": "58eacf62",
"list": "7f38c166",
"old_email": "old.webhook.contact@example.com",
"new_email": "new.webhook.contact@example.com"
}
]
}
{
"hook": "email.bounce",
"timestamp": 1422006773,
"data": [
{
"contact": "58eacf62",
"list": "7f38c166",
"campaign": "e3bcf758",
"email": "webhook.contact@not-existing.com",
"report": "Reporting-MTA: dns;mail9.mlgnsrv1.com\nReceived-From-MTA: dns;Sendserver (78.28.252.233)\nArrival-Date: Thu, 22 Jan 2015 18:09:37 +0200\n\nFinal-Recipient: rfc822;webhook.contact@not-existing.com\nAction: failed\nStatus: 5.1.1 (bad destination mailbox address)\nRemote-MTA: dns;mail.boon.lv (80.233.141.154)\nDiagnostic-Code: smtp;550 5.1.1 <webhook.contact@not-existing.com>: Recipient address rejected: User unknown in virtual mailbox table\n",
"bounce_ip": "17.172.224.47",
"bounce_ts": 1421942977
}
]
}
{
"hook": "email.open",
"timestamp": 1422006773,
"data": [
{
"contact": "58eacf62",
"list": "7f38c166",
"campaign": "e3bcf758",
"email": "webhook.contact@example.com",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1) AppleWebKit/600.2.5 (KHTML, like Gecko) Version/8.0.2 Safari/600.2.5",
"open_ip": "17.172.224.47",
"open_ts": 1421942977
}
]
}
{
"hook": "email.click",
"timestamp": 1422006773,
"data": [
{
"contact": "58eacf62",
"list": "7f38c166",
"campaign": "e3bcf758",
"email": "webhook.contact@example.com",
"url": "http://www.example.com",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1) AppleWebKit/600.2.5 (KHTML, like Gecko) Version/8.0.2 Safari/600.2.5",
"click_ip": "17.172.224.47",
"click_ts": 1421942977
}
]
}
When you provide a secret key, we create a signature and signs every webhook request you receive. That gives you the opportunity to verify that requests originated from us.
Each signed webhook request contains HTTP header X-Sendserver-Signature. The header contains a hash signature. The signature is HMAC-SHA1 hexdigest of a webhook's JSON document that is signed with your secret key. The signature is always prefixed with value 'sha1='.
To ensure validity of received data you can:
Here is a sample code how you can verify validity of received data:
const SECRET_KEY = 'MY SECRET KEY';
function verifySignature($data, $signature)
{
$hash = hash_hmac('sha1', $data, SECRET_KEY);
return $signature === 'sha1=' . $hash;
}