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 specification. See the Event Format page for details on the event structure and HTTP delivery.
The Events API is a REST API that uses resource-oriented endpoint paths, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and verbs.
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
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.
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.
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.
- Obtain OAuth credentials from Aritma
- Create a subscription with your desired event types and delivery URL
- Handle the validation webhook sent to your delivery URL
- Start receiving events at your webhook endpoint
| 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 |