Webhooks

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.

Webhook URL verification

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.

Webhook format

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": { ... }
        }
    ]
}

• timestamp - UNIX timestamp when Webhook has been sent.
• events - array of one or more events. Each event has type and data (see below for detailed examples for each event type).

Events

You can choose what event types (listed and described below) and what event sources (subscriber, account admin, API) you are intereseted in.

Subscribes

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
        }
    ]
}

Unsubscribes

{
    "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
        }
    ]
}

Profile updates

{
    "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
        }
    ]
}

Email changes

{
    "hook": "email.change",
    "timestamp": 1422006773,
    "data": [
        {
            "contact": "58eacf62",
            "list": "7f38c166",
            "old_email": "old.webhook.contact@example.com",
            "new_email": "new.webhook.contact@example.com"
        }
    ]
}

Hard bounces

{
    "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
    }
}

Email opens

{
    "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
    }
}

Email clicks

{
    "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
    }
}

Data validation

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-Mailigen-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:

• compute hash from JSON document and your secret key,
• compare it against provided signature.

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;
}