Using webhooks with robotmia

Introduction

robotmia allows you to tie data to a specific user, creating a profile. This is where you store things like their email address, where they came from, or their age. Webhooks allow you to notify yourself whenever a user first matches your campaign criteria.

Webhook targeting can be based on properties in user profiles, or events that did or did not occur within the last 90 days. For example, if you set a Last login property, you can create an webhook that notifies you about users who haven't used your service for three weeks.

Creating a webhook campaign

Each webhook campaign requires a URL to post data to. To create a new webhook campaign, navigate to the Messages report and select "Webhook" from the "Create new message" dropdown. This will give you the following form:

Targeting users

When you submit the form, it will ask you to define the targeting criteria for your message. We're keeping it simple here and restricting the message to a single user named "Joe Doe". You can use many combinations of profile properties when you're creating a real message.

Scheduling your webhook campaign

Once you've targeted your users, you just have to schedule the webhook campaign. There are two options for scheduling campaigns:

• ASAP messages: These messages are posted to your URL as soon as they match the targeting criteria. It's common for users to go from "not matching" to "matching" - many messages include a time-based requirement such as "last login was greater than two weeks ago", or one based off of other profile properties that may change.
• Scheduled messages: These messages can be set to go out at a specified time, day of week, and interval. For example, you could set your message to go out at 9am PST every Wednesday. When the message runs, it finds all the users who match the criteria you have defined and sends a post containing the associated user profiles to your URL.

Receiving webhook POSTS

A webhook is simply a remote HTTP endpoint that robotmia can POST data to when a new user matches the message criteria.

To receive a robotmia webhook, set up an endpoint on your web server exactly like you would for any other page that receives POST requests. We recommend you choose an endpoint that doesn't handle any other requests. Then specify this endpoint in robotmia during the message setup.

robotmia will send a POST request to the endpoint whenever the conditions of the message are satisfied. The POST request will be much like a standard POST request made from submitting an HTML form, with a content type of application/x‑www‑form‑urlencoded and a single parameter named users. The users parameter will contain a JSON list with data for up to 50 users. If there are more than 50 users that satisfy the message conditions, robotmia will batch these users up into sets of 50 and make a POST request for each batch.

Here's an example of the JSON we will send you:

[
   {
      "$distinct_id":"13b20239a29335",
      "$properties":{
         "$region":"California",
         "$email":"harry.q.bovik@andrew.cmu.edu",
         "$last_name":"Bovik",
         "$created":"2012-11-20T15:26:16",
         "$country_code":"US",
         "$first_name":"Harry",
         "Referring Domain":"news.ycombinator.com",
         "$city":"Los Angeles",
         "Last Seen":"2012-11-20T15:26:17",
         "Referring URL":"http://news.ycombinator.com/",
         "$last_seen":"2012-11-20T15:26:19"
      }
   },
   {
      "$distinct_id":"13a00df8730412",
      "$properties":{
         "$region":"California",
         "$email":"anna.lytics@robotmia.com",
         "$last_name":"Lytics",
         "$created":"2012-11-20T15:25:38",
         "$country_code":"US",
         "$first_name":"Anna",
         "Referring Domain":"www.quora.com",
         "$city":"Mountain View",
         "Last Seen":"2012-11-20T15:25:39",
         "Referring URL":"http://www.quora.com/What-...",
         "$last_seen":"2012-11-20T15:25:42"
      }
   }
]

You must respond with a 200 OK HTTP response for robotmia to mark the users in the message as being successfully sent to the webhook. Otherwise, we will assume the webhook for the users in that POST request failed, and we will send them again in the next message attempt.

Testing webhooks

When testing robotmia Webhooks through the Messages report, five profiles will be randomly selected from your project and delivered to the defined Webhook URL. You will want to make sure that your receiver does not inadvertently deliver these profiles as it would in production.