{ "openapi": "3.0.1", "info": { "title": "Events Subscriptions API", "description": "## Introduction\nWelcome to the Aritma Events API!\n\nOver time there will be introduced changes to the API as we continuously introduce improvements. You have the option to use a specific version or the most recent version, supported versions are available in the response header api-supported-versions.\nUse a specific version of the API by specifying the api-version header, for example api-version: 1.0. If you don't specify the header, the latest version will be used.\nIf a version has been scheduled to be removed, it will be reported through the api-supported-versions header.\n\n\nOur API uses resource-oriented endpoint paths, accepts [Json-Encoded](https://www.json.org/json-en.html) request bodies, returns [Json-Encoded](https://www.json.org/json-en.html) responses, and uses standard HTTP response codes and verbs.", "contact": { "name": "Aritma", "url": "https://aritma.com/general-inquiry/" }, "version": "v1" }, "servers": [ { "url": "https://events.dev.aritma.io", "description": "Subscriptions API Dev" }, { "url": "https://events.aritma.io", "description": "Subscriptions API" } ], "paths": { "/api/failed-events": { "get": { "tags": [ "Deadletter" ], "summary": "Gets a list of deadletters for a container.", "operationId": "GetFailedEvents", "parameters": [ { "name": "subscriptionName", "in": "query", "description": "If specified restricts result to a specific subscription.", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "description": "Divides the result into pages. (Default = 10, max = 100, min = 1)", "schema": { "type": "integer", "format": "int32", "default": 10 } }, { "name": "cursor", "in": "query", "description": "Reference for next page.", "schema": { "type": "integer", "format": "int64" } }, { "name": "fromDate", "in": "query", "description": "If specified restricts result to a time period newer than this value.", "schema": { "type": "string" } }, { "name": "toDate", "in": "query", "description": "If specified restricts result to a time period older than this value.", "schema": { "type": "string" } }, { "name": "ResourceUri", "in": "header", "description": "ResourceUri to create the event subscriptions under.", "schema": { "type": "string" } }, { "name": "TenantId", "in": "header", "description": "TenantId used by the customer.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FailedEventPage" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/failed-events/{eventId}": { "get": { "tags": [ "Deadletter" ], "summary": "Downloads a failed event.", "operationId": "DownloadFailedEvent", "parameters": [ { "name": "eventId", "in": "path", "description": "The unique event id.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "ResourceUri", "in": "header", "description": "ResourceUri to create the event subscriptions under.", "schema": { "type": "string" } }, { "name": "TenantId", "in": "header", "description": "TenantId used by the customer.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FailedEventDto" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Deadletter" ], "summary": "Deletes a failed event.", "operationId": "DeleteFailedEvent", "parameters": [ { "name": "eventId", "in": "path", "description": "The unique event id.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "ResourceUri", "in": "header", "description": "ResourceUri to create the event subscriptions under.", "schema": { "type": "string" } }, { "name": "TenantId", "in": "header", "description": "TenantId used by the customer.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/subscriptions": { "post": { "tags": [ "Subscriptions" ], "summary": "Creates a new subscription.", "description": "
Create a subscription for a set of event-types.\r\n
To complete provisioning of the subscription you must do a `GET` request against the `validationUrl` sent to the `Delivery.Url`.\r\n
Webhooks of the specified event-types will be delivered when provisioning has succeeded.", "operationId": "CreateSubscription", "parameters": [ { "name": "ResourceUri", "in": "header", "description": "ResourceUri to create the event subscriptions under.", "schema": { "type": "string" } }, { "name": "TenantId", "in": "header", "description": "TenantId used by the customer.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Aritma.Events.Subscription.Api.Models.Requests.CreateSubscriptionRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "get": { "tags": [ "Subscriptions" ], "summary": "Gets all subscriptions available.", "operationId": "GetSubscriptions", "parameters": [ { "name": "ResourceUri", "in": "header", "description": "ResourceUri to create the event subscriptions under.", "schema": { "type": "string" } }, { "name": "TenantId", "in": "header", "description": "TenantId used by the customer.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/subscriptions/{subscriptionName}": { "get": { "tags": [ "Subscriptions" ], "summary": "Gets a subscription matching the id specified.", "operationId": "GetSubscription", "parameters": [ { "name": "subscriptionName", "in": "path", "description": "The unique name of the subscription.", "required": true, "schema": { "type": "string" } }, { "name": "ResourceUri", "in": "header", "description": "ResourceUri to create the event subscriptions under.", "schema": { "type": "string" } }, { "name": "TenantId", "in": "header", "description": "TenantId used by the customer.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "Subscriptions" ], "summary": "Updates an existing subscription matching the id specified.", "description": "
Updates a subscription for a set of event-types.\r\n
To complete provisioning of the subscription you must do a `GET` request against the `validationUrl` sent to the `Delivery.Url`.\r\n
Webhooks of the specified event-types will be delivered when provisioning has succeeded.", "operationId": "UpdateSubscription", "parameters": [ { "name": "subscriptionName", "in": "path", "description": "The unique identifier of a subscription.", "required": true, "schema": { "type": "string" } }, { "name": "ResourceUri", "in": "header", "description": "ResourceUri to create the event subscriptions under.", "schema": { "type": "string" } }, { "name": "TenantId", "in": "header", "description": "TenantId used by the customer.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "A Aritma.Events.Subscription.Api.Models.Requests.UpdateSubscriptionRequest object used to Update a subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventSubscriptionStateDto" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "Subscriptions" ], "summary": "Deletes an existing subscription matching the id specified.", "operationId": "DeleteSubscription", "parameters": [ { "name": "subscriptionName", "in": "path", "description": "The unique name of a subscription.", "required": true, "schema": { "type": "string" } }, { "name": "ResourceUri", "in": "header", "description": "ResourceUri to create the event subscriptions under.", "schema": { "type": "string" } }, { "name": "TenantId", "in": "header", "description": "TenantId used by the customer.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "schemas": { "CreateSubscriptionRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "A unique identifier for the subscription.", "nullable": true, "example": "ExampleName" }, "events": { "type": "array", "items": { "type": "string" }, "description": "List of events to subscribe to.", "nullable": true, "example": [ "banking.payment.status.updated", "banking.account.transaction.received", "banking.account.balance.updated" ] }, "delivery": { "$ref": "#/components/schemas/Delivery" }, "expirationTime": { "type": "string", "description": "A date and time for when the subscription should expire.", "format": "date-time", "nullable": true, "example": "2024-01-01T00:00:00.000Z" }, "retryPolicy": { "$ref": "#/components/schemas/RetryPolicy" }, "deadletterEnabled": { "type": "boolean", "description": "A boolean describing if failed events should be stored in a container.", "nullable": true, "example": true } }, "additionalProperties": false, "description": "An object used to create a new subscription." }, "Delivery": { "type": "object", "properties": { "url": { "type": "string", "description": "A URL to the webhook that should receive the events.", "nullable": true, "example": "https://api.example.com/webhooks/events" }, "maxEventsPerBatch": { "type": "integer", "description": "Maximum number of events to be sent in a single batch.", "format": "int32", "nullable": true, "example": 10 }, "preferredBatchSizeInKiloBytes": { "type": "integer", "description": "Preferred size in kilobytes of the batches to be sent.", "format": "int32", "nullable": true, "example": 128 }, "authorizationHeader": { "type": "string", "description": "Authorization header that will be included in all webhook deliveries.", "nullable": true, "example": "Bearer mF_9.B5f-4.1JqM" } }, "additionalProperties": false, "description": "An object used to configure event delivery properties." }, "EventSubscriptionStateDto": { "type": "object", "properties": { "provisioningState": { "type": "string", "nullable": true } }, "additionalProperties": false }, "FailedEventDataDto": { "type": "object", "properties": { "deadletterId": { "type": "string", "description": "The unique identifier of the deadletter.", "nullable": true, "example": "550e8400-e29b-41d4-a716-446655440000" }, "subscriptionName": { "type": "string", "description": "The name of the subscription the event was sent to.", "nullable": true, "example": "payment-status-webhook" }, "topic": { "type": "string", "description": "The topic this deadletter belongs to.", "nullable": true, "example": "b547f0fa-52a1-4ba7-b9ef-21a8e744bba6" }, "createdOn": { "type": "string", "description": "When the deadletter was created.", "format": "date-time" }, "sizeInBytes": { "type": "integer", "description": "The size of the deadletter file.", "format": "int64", "example": 2048 } }, "additionalProperties": false, "description": "An object describing a failed event entry in a deadletter container." }, "FailedEventDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the event.", "nullable": true, "example": "550e8400-e29b-41d4-a716-446655440000" }, "eventTime": { "type": "string", "description": "The date and time the event was originally created.", "format": "date-time" }, "subject": { "type": "string", "description": "The subject or resource path associated with the event.", "nullable": true, "example": "/subscriptions/b547f0fa-52a1-4ba7-b9ef-21a8e744bba6/resource-group/9f12f079-2824-4b79-a0b4-d85028ee85cd/providers/aritma.openbanking/accounts/d2aab6d9fd7a4e6eb99c49ec6e129cb2" }, "eventType": { "type": "string", "description": "The type of event that was published.", "nullable": true, "example": "banking.payment.status.updated" }, "deliveryAttempts": { "type": "integer", "description": "The total number of delivery attempts made for this event.", "format": "int32", "example": 11 }, "lastHttpStatusCode": { "type": "integer", "description": "The HTTP status code returned by the last delivery attempt.", "format": "int32", "example": 500 }, "lastDeliveryOutcome": { "type": "string", "description": "The outcome description of the last delivery attempt.", "nullable": true, "example": "GenericError" }, "publishTime": { "type": "string", "description": "The date and time the event was published.", "format": "date-time" }, "lastDeliveryAttemptTime": { "type": "string", "description": "The date and time of the last delivery attempt.", "format": "date-time" }, "failureReason": { "type": "string", "description": "The reason the event delivery failed.", "nullable": true, "example": "TimeToLiveExceeded" }, "data": { "description": "The event payload data. This may vary given the event type.", "nullable": true, "example": { "paymentId": "p1pd127721fce494cfaa4b0311c39c12d6c", "endToEndIdentification": "0c8de8c7dcb24f0b980f9a0485dbf66f", "transactionStatus": "ACCP", "tppMessages": [], "_links": { "bulkPayment": { "href": "https://banking.aritma.io/api/bulk-payments/credit-transfer/p1b8060ed9e4e82412d9e6d781ffc1d405b", "verb": "get" }, "self": { "href": "https://banking.aritma.io/api/payments/credit-transfer/p1pd127721fce494cfaa4b0311c39c12d6c", "verb": "get" } } } } }, "additionalProperties": false, "description": "An object describing a failed event and its delivery details." }, "FailedEventPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FailedEventDataDto" }, "description": "A list of failed events.", "nullable": true }, "pageSize": { "type": "integer", "description": "The max number of items per page.", "format": "int32", "example": 10 }, "cursor": { "type": "integer", "description": "A reference for the next page.", "format": "int64", "nullable": true, "example": 1718451900000 } }, "additionalProperties": false, "description": "A paginated response containing a list of failed events." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true } }, "additionalProperties": {} }, "RetryPolicy": { "type": "object", "properties": { "ttl": { "type": "string", "description": "The time-to-live period during which failed events will be retried.", "example": "20:00:00" }, "maxEventDeliveryAttempts": { "type": "integer", "description": "Maximum number of delivery attempts for an event before it is deadlettered.", "format": "int32", "example": 30 } }, "additionalProperties": false, "description": "An object used to configure the retry policy for the subscription." }, "SubscriptionResponse": { "type": "object", "properties": { "name": { "type": "string", "description": "A unique identifier for the subscription.", "nullable": true, "example": "payment-status-webhook" }, "eventTypes": { "type": "array", "items": { "type": "string" }, "description": "List of events to subscribe to.", "nullable": true, "example": [ "banking.payment.status.updated", "banking.account.transaction.received", "banking.account.balance.updated" ] }, "delivery": { "$ref": "#/components/schemas/Delivery" }, "expirationDate": { "type": "string", "description": "A date and time for when the subscription should expire.", "format": "date-time", "nullable": true }, "retryPolicy": { "$ref": "#/components/schemas/RetryPolicy" }, "deadletterEnabled": { "type": "boolean", "description": "A boolean describing if failed events should be stored in a container.", "example": true }, "provisioningState": { "type": "string", "description": "
An event status describing the status for the subscription.\r\n
Ok - the subscription is active and operating.\r\n
Pending - the subscription is awaiting webhook validation from user.\r\n
Processing - the subscription is applying changes, will change status to Ok when done.\r\n
Aborted - the last changes was either canceled or failed.", "nullable": true, "example": "Ok" } }, "additionalProperties": false, "description": "An object describing the subscription and its properties." }, "UpdateSubscriptionRequest": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "string" }, "description": "List of events to subscribe to.", "nullable": true, "example": [ "banking.payment.status.updated", "banking.account.transaction.received", "banking.account.balance.updated" ] }, "delivery": { "$ref": "#/components/schemas/Delivery" }, "expirationTime": { "type": "string", "description": "A date and time for when the subscription should expire.", "format": "date-time", "nullable": true }, "retryPolicy": { "$ref": "#/components/schemas/RetryPolicy" }, "deadletterEnabled": { "type": "boolean", "description": "A boolean describing if failed events should be stored in a container.", "nullable": true, "example": true } }, "additionalProperties": false, "description": "An object used to update an existing subscription." } }, "securitySchemes": { "authorization_code_dev": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://id-dev.zdata.no/connect/authorize", "tokenUrl": "https://id-dev.zdata.no/connect/token", "scopes": { "api": "Access to Event Subscription Api" } } } }, "client_credentials_dev": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://id-dev.zdata.no/connect/token", "scopes": { "api": "Access to Event Subscription Api" } } } }, "authorization_code": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://id.zdata.no/connect/authorize", "tokenUrl": "https://id.zdata.no/connect/token", "scopes": { "api": "Access to Event Subscription Api" } } } }, "client_credentials": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://id.zdata.no/connect/token", "scopes": { "api": "Access to Event Subscription Api" } } } } } }, "security": [ { "authorization_code_dev": [ "api" ] }, { "client_credentials_dev": [ "api" ] }, { "authorization_code": [ "api" ] }, { "client_credentials": [ "api" ] } ] }