This quickstart walks you through creating an event subscription, completing the webhook handshake, and receiving your first event.
Steps we will go through:
- Prerequisites
- Obtain an access token
- Prepare your webhook endpoint
- Create a subscription
- Complete the webhook handshake
- Verify the subscription
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)
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>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.
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).
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
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
}'| Header | Description |
|---|---|
Authorization | Bearer token obtained in Step 1 |
ResourceUri | Defines the scope of events to deliver (see table above) |
| 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 |
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 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:
{
"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"
}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:
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.siteTo activate the subscription, perform a GET request against the webhook-request-callback URL:
curl -X GET "https://rp-westeurope.eventgrid.azure.net:553/eventsubscriptions/myfirstsubscription/validate?id=40B7A954-...&token=Kh2eFzENf..."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.
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.
After completing the handshake, confirm your subscription is active by retrieving it:
curl https://events.aritma.io/api/subscriptions/MyFirstSubscription \
-H "Authorization: Bearer <token>"{
"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.
- Learn about the Event Format to understand the structure of delivered events
- Enable
deadletterEnabledto capture failed deliveries for inspection - Check the API Reference for the full set of subscription management endpoints