Overview

Integration

User guide

API reference

Webhooks

Click webhook

What is a click webhook? #

The Click webhook is a way for Postmark to notify your application that a unique recipient clicked a tracked link in your email. This can be useful in a variety of situations, such determining effectiveness of your transactional email (can customers easily identify a reset-password link? Do they like to view order confirmations in their account dashboard? Or, simply for auditing purposes.

You may also use the Messages API to pull data about click events, but with the click webhook Postmark pushes your click events as they happen. A click webhook will push data to your application in easily parsable JSON format.

Postmark will POST one event per unique click to your webhook for clicks in links to messages sent within the last 45 days. Postmark cannot determine the uniqueness of a click after 45 days, and therefore will not post an event to your webhook for clicks in messages older than 45 days. 

A click is considered unique if the recipient has never clicked a particular link within a message within 45 days of when it was sent. 

For example:

You send a single email with a tracked link to Sally and Bob. Both of them click the link. Your server will receive two calls with unique webhook payloads. However, if either Sally or Bob clicks the link again, your server will not receive an additional event. Additionally, if your email includes multiple links, each unique link clicked by a recipient will register a new click, and trigger another call to your webhook with information about which link was clicked, by which recipient. 

For links that are older than 45 days, we will still make sure they are redirected to the original url, but they will not be considered unique, so no will be posted in this case.

Set the click webhook URL #

The click webhook URL is a server setting. You can only have one click webhook URL per server. You can enable the webhook in the following ways:

Using the Postmark website

When logged into Postmark, select the server and go to the “Settings” tab, and then the ”Outbound“ tab. You can then input your webhook URL in the “Click Webhook” field.

Using the API

You can modify the ClickHookUrl field using the Servers API to modify existing servers. You can also use the Servers API to create servers and set the ClickHookUrl field at the same time.

Click webhook data #

An example of the full JSON document that would be POSTed to your webhook URL is to the right. A brief description of some of the more interesting fields is below:

  • Recipient—the email address of the recipient that clicked the link.
  • Tag—delivery tag that was used when the message was sent.
  • OriginalLink—the link that the recipient clicked within the email.
  • ClickLocation—whether the link was clicked from HTML or Text.

Example JSON webhook data

{
  "ClickLocation": "HTML",
  "Client": {
    "Name": "Chrome 35.0.1916.153",
    "Company": "Google",
    "Family": "Chrome"
  },
  "OS": {
    "Name": "OS X 10.7 Lion",
    "Company": "Apple Computer, Inc.",
    "Family": "OS X 10"
  },
  "Platform": "Desktop",
  "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36",
  "OriginalLink": "https://example.com",
  "Geo": {
    "CountryISOCode": "RS",
    "Country": "Serbia",
    "RegionISOCode": "VO",
    "Region": "Autonomna Pokrajina Vojvodina",
    "City": "Novi Sad",
    "Zip": "21000",
    "Coords": "45.2517,19.8369",
    "IP": "8.8.8.8"
  },
  "MessageID": "00000000-0000-0000-0000-000000000000",
  "ReceivedAt": "2017-10-25T15:21:11.9065619Z",
  "Tag": "welcome-email",
  "Recipient": "john@example.com"
}

Testing the click webhook with curl #

If you’re developing on your local machine or don’t have a public URL for your API, the curl request to the right has an example webhook POST request. Replace <your-url> with the API route that you want to use for your webhook URL. The curl request will allow you to verify that your webhook URL is able to accept requests with the same JSON format that the Postmark servers will use.

Example curl call

curl <your-url> \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{ 
        "ClickLocation": "HTML", 
        "Client": { 
            "Name": "Chrome 35.0.1916.153", 
            "Company": "Google", 
            "Family": "Chrome" 
        }, 
        "OS": { 
            "Name": "OS X 10.7 Lion", 
            "Company": "Apple Computer, Inc.","Family": "OS X 10" 
        }, 
        "Platform": "Desktop",
        "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko)  Chrome/35.0.1916.153 Safari/537.36", 
        "OriginalLink": "https://example.com", 
        "Geo": { 
            "CountryISOCode": "RS", 
            "Country": "Serbia", 
            "RegionISOCode": "VO", 
            "Region": "Autonomna Pokrajina Vojvodina", 
            "City": "Novi Sad",
            "Zip": "21000",
            "Coords": "45.2517,19.8369",
            "IP": "127.0.0.1"
        }, 
        "MessageID": "00000000-0000-0000-0000-000000000000",
        "ReceivedAt": "2017-10-25T15:21:11.9065619Z",
        "Tag": "welcome-email",
        "Recipient": "john@example.com" 
      }'

How you can use the click data #

There are many possible uses for the data provided by using the click webhook:

  • Determine from when and where a recipient clicked on a link. This is especially helpful when open tracking data is not available.
  • A/B test the performance of your transactional email layouts.
  • Deactivate a link (such as a password reset link) after a single use.
  • Alert users to suspicious activity, in near real-time, if a click is registered from a different location than where they are logged in.