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.
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.
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.
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/webhookTo ensure your data is encrypted, we highly recommend using HTTPS (ssl) for your webhook url.
Testing webhooks can be a difficult process. Here are two recommendations from Postmark.
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.
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.
If Postmark does not receive a 200 response from a webhook server, we will retry the POSTing the webhooks. If we receive a 403 response, we will stop retries.
These webhooks are retried on the following schedule:
These webhooks are retried on the following schedule: