Custom Events

Learn how Custom Events work

Overview

If you want to trigger an Alloy Embedded workflow from within your own application use Custom Events.

As discussed in the Quick Start, Custom Events allow you to define when and how an Alloy Embedded workflow is invoked. Let's take an example:

Assume you need to run a workflow each time a customer creates a new ticket in your application. The workflow is part of a larger Slack integration you're building and will post a message to a Slack channel.

To pass dynamic data to Slack, you'll need to define a Custom Event schema. The schema tells Alloy Embedded what the structure of the data your planning on sending along looks like. For example, when a ticket is created in your application, you might want to send along the ticket name, associated customer email, a description, etc. This data will get sent along with the Custom Event and ultimately be included in the Slack workflow.

Therefore, we'll define a Custom Event called "Ticket Created" with a schema that looks like this:

{
  "ticketName": "String",
  "customerEmail": "String",
  "description": "String"
}

In the below example, we've added a Slack block as the destination. You can use the variables included in the Custom Event schema to dynamically populate the message as seen below.

Each time this workflow runs, it will send a Slack message with the ticket name, customer email and description you specified.

Invoking a Custom Event

To run the Custom Event, make a request to the POST /run/event endpoint and specify the event name. In our example, the event name is "Ticket Created".

You must include a userId to tell Alloy Embedded which user you want to invoke this Custom Event for and any data you want to send along as part of the schema in the data parameter as seen below.

Sample Request

curl --request POST \
     --url https://embedded.runalloy.com/2023-12/run/event \
     --header 'Authorization: bearer YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data @- <<EOF
{
  "event": "Ticket Created",
  "userId": "10101010101010",
  "data": {
    "ticketName": "String",
    "customerEmail": "[email protected]",
    "description": "I'm excited to buy Alloy Embedded!"
  }
}
EOF
const apiClient = new Embedded("YOUR_API_KEY");
await apiClient.identify(userId);

let eventName = "Ticket Created";
let bodyData = {
    "ticketName": "String",
    "customerEmail": "[email protected]",
    "description": "I'm excited to buy Alloy Embedded!"
  };
let data = await apiClient.Events.run(eventName, bodyData);
from alloy_python.embedded import Embedded

# Initialize the Embedded SDK with your API key
api_key = 'YOUR_API_KEY'
embedded = Embedded(api_key)

# Set the user ID for which you want to run an event
user_id = "user123"
embedded.Events.set_user_id(user_id)

# Specify the event and data for running the event
event_name = "Ticket Created"
event_data = {
    "ticketName": "String",
    "customerEmail": "[email protected]",
    "description": "I'm excited to buy Alloy Embedded!"
  }

# Run the specified event with the provided data
event_response = embedded.Events.run(event=event_name, data=event_data)

Wrapping Up

In this article, we looked at how to run a Custom Event and define a schema.