Event Notifications Step By Step Guide

• Table of Contents
• Overview
  • Event Types
• Sample Scenario for this Guide
• Step 1: Event Recording
• Step 2: Event Delivery Configuration
• Related Tasks

Overview

The Event Notification System processes event notifications in two parts:

1. Part 1 - Event Recording: this happens when an internal or external interaction produces an event. When event recording is enabled, GreenArrow records the new event in a queue table. Event recording is online, meaning that events are added to the queue table when the event happens.
2. Part 2 - Event Delivery: the Event Processor service periodically checks the queue table for new events, and attempts to deliver those events to a matching destination. If the event is successfully delivered, it is removed from the queue table, otherwise it is kept for later retry.

Similarly, there are two steps to configure Event Notifications, which are directly related to the two parts described above:

1. Step 1: Enable Event Recording
2. Step 2: Configure event destinations for delivery

Event Types

Engine and Studio can produce multiple types of events. For reference, take a look at the event types and the information they include in the following documents:

• Events produced by Engine
• Events produced by Studio

To receive event notifications for some of the types of events, it is necessary to enable event recording for that specific type of event.

Sample Scenario for this Guide

In this guide, we’ll use the following scenario for all examples:

1. We want notifications for the following types of events:
   • bounce_all - for messages originated in Engine and Studio
   • bounce_bad_address - for messages sent in Engine and Studio
   • scomp - for messages originated in Engine and Studio
   • engine_unsub - for messages originated in Engine
   • studio_unsub - for messages originated in Studio
2. All events should be delivered to an HTTP endpoint (over HTTP post), using a JSON payload. The URL for the endpoint is https://my-hook-server.exampledomain.com/notification.

Step 1: Event Recording

First, decide which types of events you want to be notified about. Use the links above to decide which event types you need to receive.

Note that for bounces there are two types of events: bounce_all and bounce_bad_address. The first one is used to notify that an email message wasn’t delivered. The second one notifies that the email address is invalid. Hard bounces (and soft bounces in some cases) produce both types of events.

We recommend interpreting bounce_all as failed to deliver email, and bounce_bad_address as the email address is invalid so no more messages should be sent to it.

Enable event recording for the types of events chosen, following the instructions in these documents:

• Enable event recording for Engine
• Enable event recording for Studio

For our guide’s scenario, we will enable recording only for some event types:

Enable recording for Engine events:

cd /var/hvmail/control/
echo 1 > record_events.simplemh.scomp
echo 1 > record_events.simplemh.bounce_all
echo 1 > record_events.simplemh.bounce_bad_address
echo 1 > record_events.simplemh.unsub

Enable recording for Studio events:

Connect to PostgreSQL

/var/hvmail/postgres/default/bin/psql -U greenarrow

Enable event recording

UPDATE s_system_configs 
SET event_notification_studio_click = TRUE,
    event_notification_studio_open = TRUE,
    event_notification_studio_unsub = TRUE,
    event_notification_bounce_all = TRUE,
    event_notification_bounce_bad_address = TRUE,
    event_notification_scomp = TRUE;

Logout of PostgreSQL

\d

Apply Changes

svc -t /service/hvmail-passenger /service/hvmail-studio-worker
sleep 7
svstat /service/hvmail-passenger /service/hvmail-studio-worker

After running these commands, GreenArrow will begin adding events to the queue table. The events will remain in the table until they can be delivered.

Step 2: Event Delivery Configuration

Event delivery is performed by the Event Processor service, which uses the configuration in the file /var/hvmail/control/event_processor.json. This file tells the event processor where to deliver events. The configuration file created during install instructs the Event Processor to leave events in the queue table.

Event delivery is sent to an event destination which is selected based on criteria defined in the configuration file. Each event destination contains: the conditions that events must match and the actual destination of matching events.

Here are some examples that describe event destinations:

• Deliver all events to an HTTP POST hook
• Deliver events of type bounce_all to an HTTP POST hook
• Deliver events of types bounce_all and bounce_bad_address to a MySQL database by running an SQL query
• Drop all events of type delivery_attempt

The event processor configuration file can contain multiple event destinations like those described above. If an event matches multiple destinations it will be delivered to the first matching destination in the list.

For this guide’s example, the configuration file would look like this:

{
  "configuration_mode": "json",

  "use_json_for_http_post": true,

  "event_destinations": [
    {
      "matches": { 
         "all": true 
      },
      "destination": {
        "type": "http_post",
        "url": "https://my-hook-server.exampledomain.com/notification"
      }
    }
  ]
}

The Event Processor service reads the configuration file before each run, so no service restarts are needed.

After editing the file it is always a good idea to check for syntax errors:

hvmail_event_processor --check-syntax

Related Tasks

To check the event processor logs, use the command described in this document.

If you need to stop the event processor temporarily, to troubleshoot the destination for the events for example, follow the instructions in this section of the document.