Quickstart: Create an Event Subscription

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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

Prerequisites

Before you begin, make sure you have completed the 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 for testing)

Step 1: Obtain an access token

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

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

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

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

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 - it gives you a unique URL and shows incoming requests in real time.

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:

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

curl -i -X POST \
  https://developer.aritma.com/_mock/apis/platform/events/openapi/events-openapi/api/subscriptions \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'ResourceUri: /subscriptions/<subscriptionId>/resource-groups/<resourceGroupId>' \
  -H 'TenantId: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -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

Request body schema

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

{
  "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"
}

Try it out

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:

An example handshake request received at your endpoint:

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

You have two alternatives for completing webhook validation:

HTTP/1.1 200 OK
WebHook-Allowed-Origin: eventgrid.azure.net
WebHook-Allowed-Rate: 120

Step 5: Verify the subscription

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

curl -i -X GET \
  https://developer.aritma.com/_mock/apis/platform/events/openapi/events-openapi/api/subscriptions/MyFirstSubscription \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'ResourceUri: string' \
  -H 'TenantId: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

{
  "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.

Try it out

What's next?

• Learn about the Event Format to understand the structure of delivered events
• Enable deadletterEnabled to capture failed deliveries for inspection
• Check the API Reference for the full set of subscription management endpoints