What is Webhooks?

Webhooks are an easy way to get push notifications directly into your system. A webhook is like an inverted API endpoint; instead of making a call to our API, you define a callback URL to which we will HTTP POST information as things happen. Example: you will get real time notifcation about users opening your email, clicking on links etc. Your callback URL can then execute code based on the POSTs. You can think of it as defining an API endpoint for your app that will receive output from Pepipost.

Note: Keep in mind that your servers need to be robust enough to handle a large number of requests from Pepipost’s webhooks, especially if you send or receive a lot of email.

Protecting your webhook

In order to enable webhooks so that Pepipost can communicate with your application, you will need a publicly accessible URL. Hence, it is suggested to protect this URL so that malicious attackers cannot manipulate your data.

Your Webhooks URLs should be setup to accept the POST requests coming from the Pepipost server. When you provide the URL where you want Pepipost to POST the data for events, a quick check is done through HEAD request (not POST) to ensure that the URL exists. If the URL doesn’t exist or returns something other than a 200 HTTP response to the HEAD request, Pepipost will fallback and attempt a POST request. The POST is the same type of POST as a Pepipost Webhook, except that the parameter is an empty array.

If the data POST is successfully accepted by your server then Pepipost verifies and saves the webhook URL.

IPs for firewalls

If you’re using a firewall, you can configure it to only allow requests from the IP range that Pepipost uses. Here is the subnet of IP addresses which need to be whitelisted:

202.162.242.179/255

How To Test And Debug Webhooks?

It’s always good to test Webhooks in an external or temporary environment before making changes in production.

RequestBin is one such tool to test your Webhooks. RequestBin has discontinued the publicly hosted version of its service and hence you need to create a self-hosted instance of RequestBin to do the webhooks testing.

What happens if my Webhook URL is down or can’t accept requests?

Pepipost makes the following retry increments to revoke the requests:

  1. 15 minutes after the most recent failure
  2. 45 minutes after the most recent failure
  3. 90 minutes after the most recent failure
  4. 1 hour after the most recent failure
  5. 75 minutes after the most recent failure

Once the maximum retry limit is reached for a specific event, your hook call will be treated as failed and no further retries are allowed. Data shared over HTTP POST to your pre-configured Webhooks URL.