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 Netcore Email API.

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

Protecting your webhook

In order to enable webhooks so that Netcore Email API 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 Netcore Email API server. When you provide the URL where you want Netcore Email API 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, Netcore Email API will fallback and attempt a POST request. The POST is the same type of POST as a Netcore Email API Webhook, except that the parameter is an empty array.

If the data POST is successfully accepted by your server then Netcore Email API 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 Netcore Email API uses. Here is the subnet of IP addresses which need to be whitelisted:

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?

Netcore Email API 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.