# Events API

The Aritma Events API lets you subscribe to real-time webhook notifications for events across Aritma products. Create subscriptions, configure delivery settings, and manage failed events — all through a simple REST interface.

All events follow the [CloudEvents v1.0](https://github.com/cloudevents/spec) specification. See the [Event Format](/apis/platform/events/event-format) page for details on the event structure and HTTP delivery.

## Introduction

The Events API is a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API that uses resource-oriented endpoint paths, accepts [JSON-encoded](https://www.json.org/json-en.html) request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and verbs.

## Key concepts

### Subscriptions

A subscription defines which event types you want to receive and where they should be delivered. Each subscription has:

- **Name** — A unique identifier for the subscription
- **Event types** — The list of events you want to receive
- **Delivery URL** — The webhook endpoint that will receive events
- **Retry policy** — How failed deliveries are retried (TTL and max attempts)
- **Expiration** — Optional date when the subscription automatically expires


### Webhook validation

After creating or updating a subscription, a validation request is sent to your delivery URL. You must complete a `GET` request against the `validationUrl` to activate the subscription. Events will only be delivered after validation succeeds.

### Dead-lettering

When `deadletterEnabled` is set to `true`, events that fail delivery after all retry attempts are stored for later inspection. You can list, download, and delete failed events through the dead-letter endpoints.

## Authentication

The Events API uses OAuth 2.0 for authentication. Two flows are supported:

| Flow | Use case |
|  --- | --- |
| **Authorization Code** | Interactive applications acting on behalf of a user |
| **Client Credentials** | Server-to-server integrations |


Request an access token with the `api` scope from the Aritma identity provider.

## Getting started

1. Obtain OAuth credentials from Aritma
2. [Create a subscription](/apis/platform/events/openapi/events-openapi) with your desired event types and delivery URL
3. Handle the validation webhook sent to your delivery URL
4. Start receiving events at your webhook endpoint


## Quick reference

| Endpoint | Method | Description |
|  --- | --- | --- |
| `/api/subscriptions` | `POST` | Create a new subscription |
| `/api/subscriptions` | `GET` | List all subscriptions |
| `/api/subscriptions/{name}` | `GET` | Get a specific subscription |
| `/api/subscriptions/{name}` | `PUT` | Update a subscription |
| `/api/subscriptions/{name}` | `DELETE` | Delete a subscription |
| `/api/failed-events` | `GET` | List failed events (dead letters) |
| `/api/failed-events/{id}` | `GET` | Download a failed event |
| `/api/failed-events/{id}` | `DELETE` | Delete a failed event |