# Quickstart — Create an Event Subscription

This quickstart walks you through creating an event subscription, completing the webhook handshake, and receiving your first event.

Steps we will go through:

- [Prerequisites](#prerequisites)
- [Obtain an access token](#step-1--obtain-an-access-token)
- [Prepare your webhook endpoint](#step-2--prepare-your-webhook-endpoint)
- [Create a subscription](#step-3--create-a-subscription)
- [Complete the webhook handshake](#step-4--complete-the-webhook-handshake)
- [Verify the subscription](#step-5--verify-the-subscription)


## Prerequisites

Before you begin, make sure you have completed the [Getting Started](/getting-started) guide — you'll need your `CLIENT_ID` and `CLIENT_SECRET`, and a valid access token.

You will also need:

- A publicly reachable HTTPS endpoint to receive webhooks (you can use [webhook.site](https://webhook.site) for testing)


## Step 1 — Obtain an access token

Request an access token using the **Client Credentials** flow with the `api` scope:


```bash cURL
curl -X POST https://id.aritma.io/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET \
  -d scope=api
```


```json
{
  "access_token": "<token>",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "api"
}
```

Use the `access_token` in the `Authorization` header for all subsequent requests:


```http
Authorization: Bearer <token>
```

## Step 2 — Prepare your webhook endpoint

Before creating a subscription you need a publicly reachable HTTPS endpoint. When the subscription is created, a **validation handshake** will be sent to that endpoint.

For quick testing you can use [webhook.site](https://webhook.site) — it gives you a unique URL and shows incoming requests in real time.

Tip
If you are building your own endpoint, it only needs to return a `200 OK` response for incoming `POST` requests at this stage. The actual handshake is completed by making a `GET` request to a URL provided in the handshake headers (see Step 4).

## Step 3 — Create a subscription

Send a `POST` request to `/api/subscriptions` with the event types you want to receive and your delivery configuration. The `ResourceUri` header controls the **scope** of events you will receive:

| ResourceUri | Scope |
|  --- | --- |
| `/subscriptions/{subscriptionId}` | All events for the subscription |
| `/subscriptions/{subscriptionId}/resource-groups/{resourceGroupId}` | All events for resources in a resource group |
| `/subscriptions/{subscriptionId}/resource-groups/{resourceGroupId}/providers/{provider}/{resourceType}/{resourceId}` | Only events for a specific spesific resource |


Example uri for a bank account:
`/subscriptions/b02b04ec-3d99-4228-9d77-768ab396cf3f/resource-groups/companyX/providers/aritma.openbanking/accounts/d2aab6d9fd7a4e6eb99c49ec6e129cb2`


```bash cURL
curl -X POST https://events.aritma.io/api/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -H "ResourceUri: /subscriptions/<subscriptionId>/resource-groups/<resourceGroupId>" \
  -d '{
    "name": "MyFirstSubscription",
    "events": [
      "banking.account.transaction.received",
      "banking.payment.status.updated"
    ],
    "delivery": {
      "url": "https://webhook.site/<your-unique-id>",
      "authorizationHeader": "YourSecretKey",
      "maxEventsPerBatch": 10,
      "preferredBatchSizeInKiloBytes": 128
    },
    "expirationTime": "2027-01-01T00:00:00.000Z",
    "retryPolicy": {
      "ttl": "00:10:00",
      "maxEventDeliveryAttempts": 30
    },
    "deadletterEnabled": false
  }'
```

### Required headers

| Header | Description |
|  --- | --- |
| `Authorization` | Bearer token obtained in Step 1 |
| `ResourceUri` | Defines the scope of events to deliver (see table above) |


### Request body reference

| Field | Type | Description |
|  --- | --- | --- |
| `name` | string | A unique identifier for the subscription |
| `events` | string[] | Event types to subscribe to |
| `delivery.url` | string | The webhook endpoint that will receive events |
| `delivery.authorizationHeader` | string | Value sent in the `authorization` header with every delivery |
| `delivery.maxEventsPerBatch` | integer | Maximum number of events delivered in a single request. When set to `1`, events are delivered as a single JSON object. When greater than `1`, events are delivered as a JSON array |
| `delivery.preferredBatchSizeInKiloBytes` | integer | Preferred maximum batch size in kilobytes |
| `expirationTime` | datetime | When the subscription automatically expires |
| `retryPolicy.ttl` | timespan | How long failed deliveries are retried (e.g. `00:10:00` = 10 minutes) |
| `retryPolicy.maxEventDeliveryAttempts` | integer | Maximum number of delivery retry attempts |
| `deadletterEnabled` | boolean | Whether failed events are stored for later inspection |


Batching behavior
The `maxEventsPerBatch` setting controls the delivery format. When set to **1**, each event is delivered as a single JSON object. When set to a value **greater than 1**, events are delivered as a JSON array — even if only one event is in the batch. See the [Event Format](/apis/platform/events/event-format#batched-delivery) page for an example of batched delivery.

A successful response returns `201 Created` with the subscription details. The `provisioningState` will be `Pending` until the webhook handshake is completed:


```json
{
  "name": "MyFirstSubscription",
  "eventTypes": [
    "banking.account.transaction.received",
    "banking.payment.status.updated"
  ],
  "delivery": {
    "url": "https://webhook.site/<your-unique-id>",
    "authorizationHeader": "YourSecretKey",
    "maxEventsPerBatch": 10,
    "preferredBatchSizeInKiloBytes": 128
  },
  "expirationDate": "2027-01-01T00:00:00Z",
  "retryPolicy": {
    "ttl": "00:10:00",
    "maxEventDeliveryAttempts": 30
  },
  "deadletterEnabled": false,
  "provisioningState": "Pending"
}
```

## Step 4 — Complete the webhook handshake

Immediately after the subscription is created, a validation request is sent to your webhook endpoint. The request includes these headers:

| Header | Description |
|  --- | --- |
| `authorization` | The `authorizationHeader` value you configured (e.g. `YourSecretKey`) |
| `webhook-request-callback` | The validation URL you must call to activate the subscription |
| `webhook-request-origin` | Origin of the validation request (`eventgrid.azure.net`) |


An example handshake request received at your endpoint:


```http
POST /your-webhook HTTP/1.1
authorization: YourSecretKey
webhook-request-callback: https://rp-westeurope.eventgrid.azure.net:553/eventsubscriptions/myfirstsubscription/validate?id=40B7A954-...&token=Kh2eFzENf...
webhook-request-origin: eventgrid.azure.net
host: webhook.site
```

To **activate** the subscription, perform a `GET` request against the `webhook-request-callback` URL:


```bash cURL
curl -X GET "https://rp-westeurope.eventgrid.azure.net:553/eventsubscriptions/myfirstsubscription/validate?id=40B7A954-...&token=Kh2eFzENf..."
```

Important
The validation URL is time-limited. Complete the handshake promptly after receiving it, or the subscription will remain in `Pending` state and no events will be delivered.

Tip
If you are using webhook.site for testing, you can copy the `webhook-request-callback` header value from the incoming request and open it directly in your browser to complete the validation.

## Step 5 — Verify the subscription

After completing the handshake, confirm your subscription is active by retrieving it:


```bash cURL
curl https://events.aritma.io/api/subscriptions/MyFirstSubscription \
  -H "Authorization: Bearer <token>"
```


```json
{
  "name": "MyFirstSubscription",
  "eventTypes": [
    "banking.account.transaction.received",
    "banking.payment.status.updated"
  ],
  "delivery": {
    "url": "https://webhook.site/<your-unique-id>",
    "authorizationHeader": "YourSecretKey"
  },
  "expirationDate": "2027-01-01T00:00:00Z",
  "retryPolicy": {
    "ttl": "00:10:00",
    "maxEventDeliveryAttempts": 30
  },
  "deadletterEnabled": false,
  "provisioningState": "Ok"
}
```

The `provisioningState` should now be `Ok`, meaning your subscription is active and events will be delivered to your endpoint.

## What's next?

- Learn about the [Event Format](/apis/platform/events/event-format) to understand the structure of delivered events
- Enable `deadletterEnabled` to capture failed deliveries for inspection
- Check the [API Reference](/apis/platform/events/openapi/events-openapi) for the full set of subscription management endpoints