Create Event

Define a new custom event for your organization. An event definition is a named schema — once defined, you can send events against it and use them to trigger automations.

Endpoint

POST /events

Returns: 201 Created

Headers

Header	Value	Required
Authorization	Bearer <your-api-key>	Yes
Content-Type	application/json	Yes

Body Parameters

Parameter	Type	Required	Description
name	string	Yes	Unique event name for your organization. 1–80 characters. Immutable after creation.
description	string	No	Human-readable description. Max 2000 characters.
schema	object	No	Field schema that ingested payloads are validated against. Defaults to no fields. See below.

Schema object

schema.fields is an array of field definitions. Payloads sent to this event are validated against them.

Field	Type	Description
name	string	Field identifier. Letters, digits, and underscores; must start with a letter or underscore. Max 64 characters.
type	string	One of string, number, boolean, date.
required	boolean	Whether the field must be present in every payload.

{
  "name": "order.completed",
  "description": "Fired when a customer completes checkout.",
  "schema": {
    "fields": [
      { "name": "order_id", "type": "string", "required": true },
      { "name": "total", "type": "number", "required": true },
      { "name": "is_gift", "type": "boolean", "required": false }
    ]
  }
}

Define before you send

You must create an event definition before sending events to it. A send for an undefined name returns 404.

---

Response

{
  "id": "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
  "name": "order.completed",
  "description": "Fired when a customer completes checkout.",
  "schema": {
    "fields": [
      { "name": "order_id", "type": "string", "required": true },
      { "name": "total", "type": "number", "required": true },
      { "name": "is_gift", "type": "boolean", "required": false }
    ]
  },
  "created_at": "2026-06-01T12:00:00.000Z",
  "updated_at": "2026-06-01T12:00:00.000Z"
}

Field	Type	Description
id	string	Unique event ID (UUIDv7)
name	string	Event name (unique per organization, immutable)
description	string | null	Description, or null
schema	object	The field schema ({ "fields": [...] })
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

---

Examples

cURL

curl -X POST "https://api.arsel.sa/v1/events" \
  -H "Authorization: Bearer be_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order.completed",
    "description": "Fired when a customer completes checkout.",
    "schema": {
      "fields": [
        { "name": "order_id", "type": "string", "required": true },
        { "name": "total", "type": "number", "required": true }
      ]
    }
  }'

JavaScript

const response = await fetch("https://api.arsel.sa/v1/events", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer be_your_api_key",
  },
  body: JSON.stringify({
    name: "order.completed",
    description: "Fired when a customer completes checkout.",
    schema: {
      fields: [
        { name: "order_id", type: "string", required: true },
        { name: "total", type: "number", required: true },
      ],
    },
  }),
});

const event = await response.json();
console.log(event.id);

Python

import requests

response = requests.post(
    "https://api.arsel.sa/v1/events",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer be_your_api_key",
    },
    json={
        "name": "order.completed",
        "description": "Fired when a customer completes checkout.",
        "schema": {
            "fields": [
                {"name": "order_id", "type": "string", "required": True},
                {"name": "total", "type": "number", "required": True},
            ]
        },
    },
)

print(response.json()["id"])

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer be_your_api_key");

var payload = new
{
    name = "order.completed",
    description = "Fired when a customer completes checkout.",
    schema = new
    {
        fields = new[]
        {
            new { name = "order_id", type = "string", required = true },
            new { name = "total", type = "number", required = true }
        }
    }
};

var json = System.Text.Json.JsonSerializer.Serialize(payload);
var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.arsel.sa/v1/events", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/events");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer be_your_api_key"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "name" => "order.completed",
    "description" => "Fired when a customer completes checkout.",
    "schema" => [
        "fields" => [
            ["name" => "order_id", "type" => "string", "required" => true],
            ["name" => "total", "type" => "number", "required" => true]
        ]
    ]
]));
$response = curl_exec($ch);
echo $response;
curl_close($ch);

---

Error Responses

409 Conflict

{
  "status_code": 409,
  "name": "conflict",
  "message": "An event named \"order.completed\" already exists"
}

422 Validation Error

{
  "status_code": 422,
  "name": "validation_error",
  "message": "name must be longer than or equal to 1 characters"
}

401 Unauthorized

{
  "status_code": 401,
  "name": "unauthorized",
  "message": "Invalid or missing API key"
}