How do I create webhooks in Postal?

When you use Postal to send out large amounts of e-mails to your clients, for example, you may sometimes want to collect statistics or other data about the e-mails sent out. This could be delivery statistics (for example, which, if any, email addresses result in bounces), number of clicks on links in the mail, etc. The data sent via a webhook is delivered via POST request in the form of organised json data. This guide goes through how to create a webhook via the Postal web interface.

Create a webhook

To create a webhook, proceed as follows:

1. Begin by logging on to Postal’s control panel.
2. Click on the mail server you want to create a webhook on.
   
3. Then click Webhooks in the menu.
   
4. If you have not created any webhooks before, click on Add your first webhook.
   
   If you have created webhooks before and want to add a new one, click Add another webhook instead.
   
5. You will now be able to make settings for the webhook you are creating.
   
   Fill in the information as follows:
   
   Name: Here you enter a name for your webhook so that you can distinguish multiple webhooks.
   
   URL: Enter the full URL of your script here.
   
   Enabled: If you want the hook to send data to the URL specified above, select Yes - send requests to this webhook.
   
   Events: Here you choose which data to send to your URL. The default is to send everything (Yes - send all events to this URL), but you can also choose No - I'll choose which requests to send if you only want certain data to be sent. You then get to choose what in a menu that pops up:
   
   
   Click the Create webhook button when you are done.

Your webhook is now ready to deliver data to your script.

Sample script

This guide does not cover advanced code for what a script might look like that receives data from a webhook, but this short PHP code example shows how to save all incoming data to a log file:

<?php
    $data = file_get_contents('php://input') . PHP_EOL;
    $file = 'payloads.log';
    file_put_contents($file, $data, FILE_APPEND);
?>

According to our example in the steps above, this file should be saved as postal-webhook.php and will receive all data POSTed against it to the payloads.log file.

The data is POSTed to the webhook URL as json data.