Event API

The Events API is a streamlined, easy way to build apps and bots that respond to activities in Alfred. All you need is a a secure place for us to send your events.

Tell us where to send your carefully selected event types and we'll deliver them securely with available data of the event context.

Events are sent via HTTP Post requests to a given Webhook end-point. We will send JSON-based payloads containing wrapped event types.

Event Loop

Many apps built using the Events API will follow the same abstract event-driven sequence:

1. A user creates a circumstance that triggers an event subscription to your application.

2. Your server receives a payload of JSON describing that event.

3. Your server acknowledges receipt of the event.

4. Your business logic decides what to do about that event.

5. Your server carries out that decision.

Request URL Configuration & Verification

Your Event Request URL must be confirmed before we start sending data.

URL VERIFICATION HANDSHAKE

The events sent to your Request URL contains sensitive information associated with data handled by Alfred. To ensure that events are being delivered to a server under your direct control, we must verify your ownership by issuing you a challenge request.

After you've provided your Webhook URL, we'll dispatch a HTTP POST request. We'll verify your SSL certificate and we'll send a application/json POST body containing three fields:

{ 
    "token": "Jhj5dZrVaK7ZwHHjRyZWjbDl", 
    "challenge": "3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P", 
    "type": "url_verification" 
}

RESPONDING TO THE CHALLENGE

Once you receive the event, complete the sequence by responding with HTTP 200 and the challenge attribute value.

Responses can be sent in plain text:

HTTP 200 OK
Content-type: text/plain
3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P

Or if you feel like showing off, respond with application/json:

{
  "challenge": "3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P"
}

RECEIVING EVENTS

Your Request URL will receive a request for each event raised by a data processing pipeline. One request, one event.

All events will be wrapped in a JSON “envelope” with the following structure:

{
  "event_id": "unique identifier for the event",
  "event_type": "what type of event happened",
  "event_time": "unix timestamp representing the time when the event happened",
  "event" : {
    "description": "complex event structure which changes depending on the event being sent."
  } 
}