houdini/docs/object_event_hook_configs.md

Object Event Hooks Configurations

With those configurations, nonprofits are able to set up webhook configurations for given events that happen to that nonprofit. As an example, a nonprofit might want to contact a particular API A when the a supporter is created or when a tag_master is added while they might want to contact a different API B when a supporter is deleted.

Currently, Houdini supports sending triggers to OpenFn.

Setup Instructions

OpenFn side

• Navigate to OpenFn and sign up;

• Set up an authentication method on Access and Security option, by clicking on Add new security protocol. Choose the API Key auth type;

• Create a trigger of "Message Trigger" type and define which filter should be in your trigger payload:

  

  In this case, we'll be sending an event of type supporter_note.created.

• Navigate to the project view and copy your inbox link.

Creating a job that sends an e-mail using Mailgun

• Create an account on Mailgun (for the sake of testing, a free account is enough);

• For using the sandbox domain Mailgun provides for testing, add your e-mail as an authorized recipient:

  

• On OpenFn, set up your Mailgun credentials on Credentials;

• Create a new job on Jobs, by clicking the + icon and connect to the corresponding trigger;

• Add the script that the job is going to execute on Execution. An example for Mailgun could be:

send({
  from: '<your-email>@gmail.com',
  to: '<your-email>@gmail.com',
  subject: 'Supporter note created!',
  text: `A supporter note was created for the supporter
  ${dataValue('data.object.supporter.name')(state)} of the nonprofit
  ${dataValue('data.object.nonprofit.name')(state)}.`,
})

To access your payload data from your job, you can use dataValue('someKey')(state)

Application side

For now, there is no UI for the creation of the configuration for the Object Event Hooks. The following instructions allow the creation of the configuration using the console:

rails c

# Set up for the ObjectEventHookConfig
nonprofit = Nonprofit.last
webhook_service = :open_fn
object_event_type = 'supporter_note.created'
configuration = {
    headers: { 'x-api-key': <your api key> },
    webhook_url: <your inbox url>
  }
attributes = {
    webhook_service: webhook_service,
    configuration: configuration,
    object_event_types: [ object_event_type ]
  }
object_event_hook_config =
  nonprofit.object_event_hook_configs.create(attributes)

In the application, navigate to the nonprofit supporters' view:

Create a new supporter and open their details or simply open the details of an existing one.

Click the + Note button, write a note and click Submit.

The OpenFn inbox is going to show a successful run for your job, and on the run details you'll be able to see that the mail sending was enqueued, and in a few instants, you'll have received an e-mail with the event details.

OpenFn successful run