Webhooks

Webhooks

Webhook is a development method that enables you to receive notifications in real time. It is a mechanism similar to API, but in this case, all communication goes the opposite way, meaning that you are the one defining the URL callback where you will receive information about the activities in the system. In practice, you need to write a script that will be able to process the request sent from FreshMail’ system.

At this moment, we offer a webhooks version that can notify you, via HTTP POST about activities related to your campaigns (clicks, opens etc.).

For developers

This mechanism requires a script that will be able to receive data and confirm their reception.

Requirements

First, and very important thing to keep in mind that the script you create will have to handle a large number of requests. For example, it has to be able to process 1000 requests within 5 seconds. In case this fails, you need to have settings on your own side that will inform us about the outcome. If the process lasts longer than 5 seconds-our system will recognise it as an the error and those information will be sent once again.

Debugging

It is very hard to perform, therefore FreshMail interface has an option that enables the overview of previous mistakes in communication between FreshMail and your URL.

Webhooks settings

After you activate Webhooks, FreshMail will send all information about events to your URL over your HTTP POST. The most common use of this type of integration is supervision of for ex: subscriber’s activities, information about click  and opens, synchronisation of subscribers that have unsubscribed, identification of the ones that did not react to any or one of the campaigns, etc.

Configuration

After you activate Webhooks, FreshMail will send all information about events to your URL over your HTTP POST. The most common use of this type of integration is supervision of for ex: subscriber’s activities, information about click  and opens, synchronization of subscribers that have unsubscribed, identification of the ones that did not react to any or one of the campaigns etc.

               http(s)://my-domain.com/api/freshmail/webhooks

Possible errors

If right after testing (when you click on “test connection”) you receive an information that an error occurred there is no reason for you to be worried. At this point, you still do not have an appropriate script on that location.

If, physically, there is no  application that would respond to the our API request, information about the error will appear in CURL library, in the form below:

Request error (curl) 404 - HTTP/1.1 404 Not Found

In that case, we have to add a script that will be able to support the request. Once we do it,  the “error”information should change into:

The server replied but in an incorrect format

This means that the script has been found by our application, but unfortunately does not respond properly to the request, i.e. does not match the data in the correct format.

Test requests

The very first step of this phase it to make sure your script is able to handle test requests.. It is a starting point of all communication. These requests can be sent directly through FreshMail using the “test connection” button, or you can do it yourself using the CURL library

curl -X POST -d '{"test":"1"}' http(s)://my-domain.com/api/freshmail/webhooks

FreshMail awaits for a notice of 2xx HTTP code as an answer to the request above. Additionally, the response needs to contain the answer below:   

{"status":"ok"}

This is a way for you to test the entire communication. If these tests work properly it means there are no connection problems between FreshMail’ server and you own.

Events

Your webhooks are going to receive an HTTP POST request containing an array of the event objects in JSON format. Every individual request can contain up to 1000 events and will be sent with the least possible delay in the actions that a recipients is making within the email.

Examples of HTTP POST:

[
    {
        "campaign":"nsqqmsb52q",
        "email":"john.doe@freshmail.com",
        "event":"open",
        "timestamp":1439889386,
        "attempt":1,
        "hash":"97db930155"
    },{
        "campaign":"nsqqmsb52q",
        "email":"john@freshmail.com",
        "event":"unsubscribe",
        "timestamp":1439889404,
        "attempt":1,
        "hash":"ccec7ad7f1"
    },{
        "campaign":"nsqqmsb52q",
        "email":"antonio@freshmail.com",
        "event":"open",
        "timestamp":1439889604,
        "attempt":1,
        "hash":"324f4075a6"
    },{
        "campaign":"nsqqmsb52q",
        "email":"samuel@freshmail.pl",
        "event":"open",
        "timestamp":1439892486,
        "attempt":1,
        "hash":"9d041d9ab3"
    }
]

Types of events

Event Comment
Open recipient opened the HTML content
Click recipient clicked the link within the message
Unsubscribe recipient clicked the unsubscribe link

Default events parameters:

Property Type Comment
event String Event type(described above)
campaign String  Campaign hash (10 characters)
timestamp Integer Time of the event (unix timestamp)
attempt Integer Attempts of event delivery
hash String Event ID (10  to 50 characters)

Event ID is used to confirm the delivery.

IMPORTANT: Event ID is not unique.

If two events have the same tag this means that they are carrying the same information. For example, if a recipient opens a given campaign 2 times within a few seconds- event ID will be different because the action occurred at different time. However, if a recipient manages to open 2 emails within the same second- event ID will be the same, and they will carry the same information.

Parameters of individual events

The section below shows and example of every type of event. Remember that every element is a single array sent through HTTP POST. Event fields are not arranged in any specific order.

Open

Event informing us that the recipient has opened the HTML.

{
    "campaign":"campaign_hash",
    "email":"email@example.com",
    "event":"open",
    "timestamp":1439892486,
    "attempt":1,
    "hash":"event_id"
}

Clicks

Event informing us that the recipient has clicked the link.

{
    "campaign":"campaign_hash",
    "email":"email@example.com",
    "event":"click",
    "timestamp":1439971916,
    "attempt":1,
    "hash":"event_id",
    "url":"http://your-link.com/blog/"
}

Unsubscribe

event that tells us  that the recipient has clicked a resignation link.

{
    "campaign":"campaign_hash",
    "email":"email@example.com",
    "event":"unsubscribe",
    "timestamp":1439889404,
    "attempt":1,
    "hash":"event_id"
}

Confirmation of receipt

Each event has to be confirmed to (the) FreshMail. In this confirmation we expect the code HTTP 200 or JSON array with every  individual event confirmed. This request  needs to contain:

Field Type Vaule
hash String Hash of the event in question (the one you are confirming)
status Boolean Contains information about the event status

Below is an example how that confirmation may look:

[
    {
        "campaign":"nsqqmsb52q",
        "email":"john.doe@freshmail.com",
        "event":"open",
        "timestamp":1439889386,
        "attempt":1,
        "hash":"97db930155"
    },{
        "campaign":"nsqqmsb52q",
        "email":"john@freshmail.com",
        "event":"unsubscribe",
        "timestamp":1439889404,
        "attempt":1,
        "hash":"ccec7ad7f1"
    }
]

And the response should look like this:

 

[
{
      "hash":"97db930155",
      "status":true
    },{
      "hash":"ccec7ad7f1",
      "status":true
    }
]

Webhooks - debugging

When it comes to webhooks, debugging is a difficult to implement. First, you need to make sure that your code responds with code 200. You can use some of free, public tools for debugging, like the ones given below:

RequestBin

Can be used as a tool for monitoring requests coming from Freshmail’ servers.

First thing you need to do is create a Bin Url.

It should look like this:

RequestBin

Can be used as a tool for monitoring requests coming from Freshmail’ servers. First thing you need to do is create a Bin Url.

It should look like this:

http://requestb.in/1i379i31

Now, you are ready to set your URL into FreshMail Webhooks configuration. After you click “test connection”, and go back to RequestBin- refresh the page and you will see which requests have been sent from FreshMail to your URL.

CURL

Another simple way to test the communication is by using CURL library and preparing a special requests that will simulate the data sent by FreshMail’ servers.

Example:

Test request:

curl -X POST -d '{"test":"1"}' http(s)://my-domain.com/api/freshmail/webhooks

Request with one event:

curl -X POST -d '[{"campaign":"jsid73ejd0","email":"email@example.com","event":"open","timestamp":1439989130,"attempt":1,"hash":"32a3c15e44"}]' http(s)://my-domain.com/api/freshmail/webhooks

Request with multiple events:

curl -X POST -d [{"campaign":"kais7nw3ee","email":"email@example.com","event":"open","timestamp":1439989207,"attempt":1,"hash":"0093332079"},{"campaign":"kais7nw3ee","email":"email@example.com","event":"open","timestamp":1439989208,"attempt":4,"hash":"ae9e92b9fe"},{"campaign":"kais7nw3ee","email":"email@example.com","event":"unsubscribe","timestamp":1439889404,"attempt":2,"hash":"ccec7ad7f1"}]
' http(s)://my-domain.com/api/freshmail/webhooks