# 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 <a href="#event-loop" id="event-loop"></a>

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 <a href="#request-url-configuration-and-verification" id="request-url-configuration-and-verification"></a>

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

#### URL VERIFICATION HANDSHAKE <a href="#url-verification-handshake" id="url-verification-handshake"></a>

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 <a href="#responding-to-the-challenge" id="responding-to-the-challenge"></a>

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 <a href="#receiving-events" id="receiving-events"></a>

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."
  } 
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tagshelf.dev/event-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.