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 your retention period (which is 45 days by default, but the data retention period can be customized from 7 to 365 days). Postmark cannot determine the uniqueness of a click after your retention period expires, and therefore will not post an event to your webhook for clicks in messages older than your retention period. 

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

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 your retention period, 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.

Note: The datetime for the ReceivedAt field will be in ISO 8601 format.

What can I do with click events?

• 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.

Create a new webhook #

Using the Postmark website

When logged into Postmark, select the Server, the Message Stream, and then go to the Webhooks tab. Choose Add webhook and input your webhook URL in Webhook URL and then select the Link Click checkbox.

Using the API

You can modify the Click field using the Webhooks API to edit an existing Webhook. You can also use the Webhooks API to create webhooks and set the Click field at the same time. After setting the URL, verify the webhook so you know it's reachable before events start flowing. See Verifying your webhook.

Event 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.
• Metadata—custom metadata that was included in the email.
• OriginalLink—the link that the recipient clicked within the email.
• ClickLocation—whether the link was clicked from HTML or Text.
• ReceivedAt—the timestamp of when the link was clicked.

Testing events #

If you’re developing on your local machine or don’t have a public URL for your API, the cURL request example below sends a test webhook to your service. Replace <your-webhook-url>, run the command, and verify it accepts and processes the event as expected.