Overview

Integration

User guide

API reference

Webhooks

Webhooks overview

What is a webhook? #

A webhook is the act of Postmark making an HTTP POST request to your application’s API when an event occurs. This way Postmark is able to immediately notify you when an event occurs and your application doesn’t have to perform complicated polling of Postmark’s API to determine if something new occurred.

Note: The datetimes within webhook data will be in ISO 8601 format.

Protecting your webhook #

For Postmark to communicate with your application, you will need a publicly accessible URL. You’ll want to protect this URL so that malicious actors cannot manipulate your data.

IPs for firewalls

If you’re using a firewall, you can configure it to only allow requests from the IP range that Postmark uses. You can find the IPs that Postmark uses for webhook requests on our support page. The origin IP address can change for each attempt.

Basic HTTP authentication

Another easy way to protect your API is through basic HTTP authentication. Almost all web servers can be configured to require a user name and password for access to a URL. You can configure your webhook URL with basic HTTP authentication by adding the user name and password to the URL https://example.com/webhook in the following format and setting the result as the webhook URL:

https://<username>:<password>@example.com/webhook

To ensure your data is encrypted, we highly recommend using HTTPS (ssl) for your webhook url.

Testing your webhook #

Testing webhooks can be a difficult process. Here are two recommendations from Postmark.

Using curl

A great tool for dealing with APIs (and many other things) is curl. In this context, you can use curl to make HTTP requests to your API in the same way that Postmark would make requests to your API. You can find an example curl call in each individual webhook section.

Using RequestBin

RequestBin is a great service to inspect HTTP requests. You can create a temporary RequestBin URL and use the temporary URL as your webhook URL in Postmark. RequestBin will then record the HTTP requests and allow you to inspect the HTTP requests to verify headers, JSON bodies, and other information about the request. This will provide you with information about the HTTP requests used in the webhook if you don’t have a public URL set up yet and want to start developing right away.

Retry attempts #

If Postmark does not receive a 200 response from a webhook server, we will retry the POSTing the webhooksIf we receive a 403 response, we will stop retries.

Bounce and Inbound webhooks

These webhooks are retried on the following schedule:

  • 1 Min
  • 5 mins
  • 10 mins (x 3)
  • 15 mins
  • 30 mins
  • 1 hour
  • 2 hours
  • 6 hours

Click, Open, Delivered, and Subscription change webhooks

These webhooks are retried on the following schedule:

  • 1 min
  • 5 mins
  • 15 mins