> For the complete documentation index, see [llms.txt](https://apidocs.arionbanki.is/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.arionbanki.is/business-apis/webhooks-api/webhooks-api-reference.md).
# Webhooks API Reference
Download OpenAPI yaml file
## POST /api/v1/subscriptions
> Creates a new event subscription.
```json
{"openapi":"3.0.1","info":{"title":"Open Banking Events - Event Subscriptions & Webhooks","version":"1.0"},"servers":[{"url":"https://apigw.arionbanki.is/events","description":"Production"},{"url":"https://apigwsandbox.arionbanki.is/events","description":"Sandbox"}],"security":[{"oauth2":["profile","b2b"]}],"components":{"securitySchemes":{"oauth2":{"type":"apiKey","description":"JWT bearer token in the Authorization header.","name":"Authorization","in":"header"}},"schemas":{"CreateSubscriptionRequest":{"required":["callbackUrl"],"type":"object","properties":{"callbackUrl":{"type":"string","nullable":true},"eventTypes":{"type":"array","items":{"$ref":"#/components/schemas/EventType"},"nullable":true},"description":{"type":"string","nullable":true},"subjectScope":{"$ref":"#/components/schemas/SubjectScope"}},"additionalProperties":false},"EventType":{"enum":["Claim"],"type":"string"},"SubjectScope":{"enum":["Self","OnBehalfOfUsers"],"type":"string"},"Subscription":{"required":["callbackUrl"],"type":"object","properties":{"subscriptionId":{"type":"string","format":"uuid","nullable":true},"callbackUrl":{"type":"string","nullable":true},"eventTypes":{"type":"array","items":{"$ref":"#/components/schemas/EventType"},"nullable":true},"description":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"subjectScope":{"$ref":"#/components/schemas/SubjectScope"},"deliveryEnabled":{"type":"boolean"},"disabledReason":{"type":"string","nullable":true},"disabledAt":{"type":"string","format":"date-time","nullable":true},"enabledAt":{"type":"string","format":"date-time","nullable":true},"signingSecret":{"type":"string","nullable":true},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"},"nullable":true}},"additionalProperties":false},"Link":{"type":"object","properties":{"rel":{"type":"string","nullable":true},"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false}}},"paths":{"/api/v1/subscriptions":{"post":{"tags":["EventSubscription"],"summary":"Creates a new event subscription.","parameters":[{"name":"X-Request-ID","in":"header","description":"A unique identifier for the request","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Ocp-Apim-Subscription-Key","in":"header","description":"The API key used for authentication and authorization.","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"The subscription details to create.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscriptionRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}}}}}}}
```
## GET /api/v1/subscriptions
> Retrieves all event subscriptions for the authenticated user.
```json
{"openapi":"3.0.1","info":{"title":"Open Banking Events - Event Subscriptions & Webhooks","version":"1.0"},"servers":[{"url":"https://apigw.arionbanki.is/events","description":"Production"},{"url":"https://apigwsandbox.arionbanki.is/events","description":"Sandbox"}],"security":[{"oauth2":["profile","b2b"]}],"components":{"securitySchemes":{"oauth2":{"type":"apiKey","description":"JWT bearer token in the Authorization header.","name":"Authorization","in":"header"}},"schemas":{"Subscription":{"required":["callbackUrl"],"type":"object","properties":{"subscriptionId":{"type":"string","format":"uuid","nullable":true},"callbackUrl":{"type":"string","nullable":true},"eventTypes":{"type":"array","items":{"$ref":"#/components/schemas/EventType"},"nullable":true},"description":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"subjectScope":{"$ref":"#/components/schemas/SubjectScope"},"deliveryEnabled":{"type":"boolean"},"disabledReason":{"type":"string","nullable":true},"disabledAt":{"type":"string","format":"date-time","nullable":true},"enabledAt":{"type":"string","format":"date-time","nullable":true},"signingSecret":{"type":"string","nullable":true},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"},"nullable":true}},"additionalProperties":false},"EventType":{"enum":["Claim"],"type":"string"},"SubjectScope":{"enum":["Self","OnBehalfOfUsers"],"type":"string"},"Link":{"type":"object","properties":{"rel":{"type":"string","nullable":true},"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false}}},"paths":{"/api/v1/subscriptions":{"get":{"tags":["EventSubscription"],"summary":"Retrieves all event subscriptions for the authenticated user.","parameters":[{"name":"X-Request-ID","in":"header","description":"A unique identifier for the request","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Ocp-Apim-Subscription-Key","in":"header","description":"The API key used for authentication and authorization.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}}}}}}}}}}
```
## GET /api/v1/subscriptions/{subscriptionId}
> Retrieves a specific event subscription by its unique identifier.
```json
{"openapi":"3.0.1","info":{"title":"Open Banking Events - Event Subscriptions & Webhooks","version":"1.0"},"servers":[{"url":"https://apigw.arionbanki.is/events","description":"Production"},{"url":"https://apigwsandbox.arionbanki.is/events","description":"Sandbox"}],"security":[{"oauth2":["profile","b2b"]}],"components":{"securitySchemes":{"oauth2":{"type":"apiKey","description":"JWT bearer token in the Authorization header.","name":"Authorization","in":"header"}},"schemas":{"Subscription":{"required":["callbackUrl"],"type":"object","properties":{"subscriptionId":{"type":"string","format":"uuid","nullable":true},"callbackUrl":{"type":"string","nullable":true},"eventTypes":{"type":"array","items":{"$ref":"#/components/schemas/EventType"},"nullable":true},"description":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"subjectScope":{"$ref":"#/components/schemas/SubjectScope"},"deliveryEnabled":{"type":"boolean"},"disabledReason":{"type":"string","nullable":true},"disabledAt":{"type":"string","format":"date-time","nullable":true},"enabledAt":{"type":"string","format":"date-time","nullable":true},"signingSecret":{"type":"string","nullable":true},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"},"nullable":true}},"additionalProperties":false},"EventType":{"enum":["Claim"],"type":"string"},"SubjectScope":{"enum":["Self","OnBehalfOfUsers"],"type":"string"},"Link":{"type":"object","properties":{"rel":{"type":"string","nullable":true},"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"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":{}}}},"paths":{"/api/v1/subscriptions/{subscriptionId}":{"get":{"tags":["EventSubscription"],"summary":"Retrieves a specific event subscription by its unique identifier.","parameters":[{"name":"subscriptionId","in":"path","description":"The unique identifier of the subscription to retrieve.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Request-ID","in":"header","description":"A unique identifier for the request","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Ocp-Apim-Subscription-Key","in":"header","description":"The API key used for authentication and authorization.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}}
```
## PUT /api/v1/subscriptions/{subscriptionId}
> Updates an existing event subscription.
```json
{"openapi":"3.0.1","info":{"title":"Open Banking Events - Event Subscriptions & Webhooks","version":"1.0"},"servers":[{"url":"https://apigw.arionbanki.is/events","description":"Production"},{"url":"https://apigwsandbox.arionbanki.is/events","description":"Sandbox"}],"security":[{"oauth2":["profile","b2b"]}],"components":{"securitySchemes":{"oauth2":{"type":"apiKey","description":"JWT bearer token in the Authorization header.","name":"Authorization","in":"header"}},"schemas":{"UpdateSubscriptionRequest":{"required":["callbackUrl"],"type":"object","properties":{"callbackUrl":{"type":"string","nullable":true},"eventTypes":{"type":"array","items":{"$ref":"#/components/schemas/EventType"},"nullable":true},"description":{"type":"string","nullable":true},"subjectScope":{"$ref":"#/components/schemas/SubjectScope"}},"additionalProperties":false},"EventType":{"enum":["Claim"],"type":"string"},"SubjectScope":{"enum":["Self","OnBehalfOfUsers"],"type":"string"},"Subscription":{"required":["callbackUrl"],"type":"object","properties":{"subscriptionId":{"type":"string","format":"uuid","nullable":true},"callbackUrl":{"type":"string","nullable":true},"eventTypes":{"type":"array","items":{"$ref":"#/components/schemas/EventType"},"nullable":true},"description":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"subjectScope":{"$ref":"#/components/schemas/SubjectScope"},"deliveryEnabled":{"type":"boolean"},"disabledReason":{"type":"string","nullable":true},"disabledAt":{"type":"string","format":"date-time","nullable":true},"enabledAt":{"type":"string","format":"date-time","nullable":true},"signingSecret":{"type":"string","nullable":true},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"},"nullable":true}},"additionalProperties":false},"Link":{"type":"object","properties":{"rel":{"type":"string","nullable":true},"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"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":{}}}},"paths":{"/api/v1/subscriptions/{subscriptionId}":{"put":{"tags":["EventSubscription"],"summary":"Updates an existing event subscription.","parameters":[{"name":"subscriptionId","in":"path","description":"The unique identifier of the subscription to update.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Request-ID","in":"header","description":"A unique identifier for the request","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Ocp-Apim-Subscription-Key","in":"header","description":"The API key used for authentication and authorization.","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"The updated subscription details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}}
```
## DELETE /api/v1/subscriptions/{subscriptionId}
> Deletes a specific event subscription by its unique identifier.
```json
{"openapi":"3.0.1","info":{"title":"Open Banking Events - Event Subscriptions & Webhooks","version":"1.0"},"servers":[{"url":"https://apigw.arionbanki.is/events","description":"Production"},{"url":"https://apigwsandbox.arionbanki.is/events","description":"Sandbox"}],"security":[{"oauth2":["profile","b2b"]}],"components":{"securitySchemes":{"oauth2":{"type":"apiKey","description":"JWT bearer token in the Authorization header.","name":"Authorization","in":"header"}},"schemas":{"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":{}}}},"paths":{"/api/v1/subscriptions/{subscriptionId}":{"delete":{"tags":["EventSubscription"],"summary":"Deletes a specific event subscription by its unique identifier.","parameters":[{"name":"subscriptionId","in":"path","description":"The unique identifier of the subscription to delete.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Request-ID","in":"header","description":"A unique identifier for the request","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Ocp-Apim-Subscription-Key","in":"header","description":"The API key used for authentication and authorization.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}}
```
## Verifies the subscriber's webhook endpoint and, on a 2xx response, activates the subscription (ADR-029).
> Sends a signed, encrypted test delivery to the subscription's callback URL. A subscription is\
> created disabled (pending activation); the first successful (2xx) verify turns delivery on and\
> real events begin to flow. Bypasses NServiceBus / RabbitMQ in both production and sandbox.
```json
{"openapi":"3.0.1","info":{"title":"Open Banking Events - Event Subscriptions & Webhooks","version":"1.0"},"servers":[{"url":"https://apigw.arionbanki.is/events","description":"Production"},{"url":"https://apigwsandbox.arionbanki.is/events","description":"Sandbox"}],"security":[{"oauth2":["profile","b2b"]}],"components":{"securitySchemes":{"oauth2":{"type":"apiKey","description":"JWT bearer token in the Authorization header.","name":"Authorization","in":"header"}},"schemas":{"EventType":{"enum":["Claim"],"type":"string"},"MockEventDeliveryResponse":{"type":"object","properties":{"subscriptionId":{"type":"string","format":"uuid"},"eventType":{"$ref":"#/components/schemas/EventType"},"callbackUrl":{"type":"string","nullable":true},"statusCode":{"type":"integer","format":"int32","nullable":true},"durationMs":{"type":"integer","format":"int64"},"deliveredAt":{"type":"string","format":"date-time"}},"additionalProperties":false},"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":{}}}},"paths":{"/api/v1/subscriptions/{subscriptionId}/verify":{"post":{"tags":["EventSubscription"],"summary":"Verifies the subscriber's webhook endpoint and, on a 2xx response, activates the subscription (ADR-029).","description":"Sends a signed, encrypted test delivery to the subscription's callback URL. A subscription is\ncreated disabled (pending activation); the first successful (2xx) verify turns delivery on and\nreal events begin to flow. Bypasses NServiceBus / RabbitMQ in both production and sandbox.\n","parameters":[{"name":"subscriptionId","in":"path","description":"The unique identifier of the subscription to verify/activate.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"eventType","in":"query","description":"The type of test event to send. Must be one of the subscription's enabled events.","required":true,"schema":{"$ref":"#/components/schemas/EventType"}},{"name":"X-Request-ID","in":"header","description":"A unique identifier for the request; forwarded to the callback as X-Request-ID.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Ocp-Apim-Subscription-Key","in":"header","description":"The API key used for authentication and authorization.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MockEventDeliveryResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MockEventDeliveryResponse"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MockEventDeliveryResponse"}}}}}}}}}
```