OpenAPI Specification
openapi: 3.0.3
info:
title: Astrada bank-accounts webhooks API
version: '2024-02-28'
contact:
email: developer@astrada.co
description: 'Welcome to our API Reference. 👋
'
servers:
- url: https://api.astrada.co
security: null
tags:
- name: webhooks
description: Manage webhooks
paths:
/webhooks:
post:
tags:
- webhooks
summary: Create webhook
description: Registers a new webhook for capturing event notifications.
operationId: createWebhook
security:
- main-auth:
- webhooks:write
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
url:
type: string
format: uri
description:
type: string
eventTypes:
$ref: '#/components/schemas/webhook-event-types'
subaccountId:
type: string
format: uuid
enabled:
type: boolean
default: true
required:
- url
- eventTypes
- subaccountId
examples:
Card transaction events:
value:
url: https://example-api.com/path
description: Example of Webhook description
eventTypes:
- transactionmessage.created
subaccountId: f297d659-c13d-4219-aeaa-e10a845140a5
Bank linking events:
value:
url: https://example-api.com/bank-events
description: Bank linking lifecycle and bank-record events
eventTypes:
- banklink.completed
- bankaccount.state_changed
- banktransaction.created
- transaction.match.created
subaccountId: f297d659-c13d-4219-aeaa-e10a845140a5
responses:
'201':
description: Successful operation
content:
application/hal+json:
schema:
allOf:
- $ref: '#/components/schemas/webhook'
- type: object
properties:
secret:
type: string
description: Only returned on Webhook creation
required:
- secret
examples:
Example Create Webhook Response:
value:
_links:
self:
href: /webhooks/3a45ba7f-8d8f-4f6a-86a5-a17ea0328241
id: 3a45ba7f-8d8f-4f6a-86a5-a17ea0328241
url: https://example-api.com/path
description: Example of Webhook description
eventTypes:
- transactionmessage.created
subaccountId: f297d659-c13d-4219-aeaa-e10a845140a5
createdAt: '2023-12-19T14:45:00Z'
updatedAt: '2023-12-19T14:45:00Z'
enabled: true
secret: ODk4ZDAxYjYtZjM4NC00MzdmLWEzMDMtM2M0NjA1NWY5NTQ5
'400':
$ref: '#/components/responses/bad-request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not-found'
'500':
$ref: '#/components/responses/server-error'
get:
parameters:
- $ref: '#/components/parameters/subaccount-id'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/cursor'
tags:
- webhooks
summary: List webhooks
description: 'Returns all webhooks configured under the account, optionally filtered by subaccount, including details on the events each webhook is subscribed to.
This endpoint supports [cursor-based pagination](https://docs.astrada.co/reference/pagination).
'
operationId: listWebhooks
security:
- main-auth:
- webhooks:read
responses:
'200':
description: Successful operation
content:
application/hal+json:
schema:
type: object
additionalProperties: false
description: Astrada's Webhook resources.
required:
- _links
- _embedded
properties:
_links:
type: object
properties:
self:
$ref: '#/components/schemas/link'
next:
$ref: '#/components/schemas/link'
_embedded:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/webhook'
examples:
Example List Webhooks Response:
value:
_links:
self:
href: /webhooks
_embedded:
webhooks:
- _links:
self:
href: /webhooks/3a45ba7f-8d8f-4f6a-86a5-a17ea0328241
id: 3a45ba7f-8d8f-4f6a-86a5-a17ea0328241
url: https://example-api.com/path
description: Example of Webhook description
eventTypes:
- transactionmessage.created
subaccountId: f297d659-c13d-4219-aeaa-e10a845140a5
createdAt: '2023-12-19T14:45:00Z'
updatedAt: '2023-12-19T14:45:00Z'
enabled: true
- _links:
self:
href: /webhooks/627f9c6d-ec9f-4118-84f3-97a77f447e32
id: 627f9c6d-ec9f-4118-84f3-97a77f447e32
url: https://example-api.com/path
description: Example of Webhook description
eventTypes:
- transactionmessage.created
subaccountId: f297d659-c13d-4219-aeaa-e10a845140a5
createdAt: '2023-12-19T14:46:00Z'
updatedAt: '2023-12-19T14:46:00Z'
enabled: true
Example no Webhooks found:
value:
_links:
self:
href: /webhooks
_embedded:
webhooks: []
'400':
$ref: '#/components/responses/bad-request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/server-error'
/webhooks/{webhookId}:
parameters:
- $ref: '#/components/parameters/webhook-id'
delete:
tags:
- webhooks
summary: Delete webhook
description: Remove a configured webhook by its identifier. Results in the resource being deleted and no longer available.
operationId: deleteWebhook
security:
- main-auth:
- webhooks:write
responses:
'204':
description: Successful operation
'400':
$ref: '#/components/responses/bad-request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not-found'
'500':
$ref: '#/components/responses/server-error'
get:
tags:
- webhooks
summary: Retrieve webhook
description: Returns detailed information about a specific webhook by its identifier, including its configuration and event subscription details.
operationId: getWebhook
security:
- main-auth:
- webhooks:read
responses:
'200':
description: Successful operation
content:
application/hal+json:
schema:
$ref: '#/components/schemas/webhook'
examples:
Example Get Webhook Response:
$ref: '#/components/examples/webhook'
'400':
$ref: '#/components/responses/bad-request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not-found'
'500':
$ref: '#/components/responses/server-error'
patch:
tags:
- webhooks
summary: Update webhook
description: Updates the configuration of an existing webhook, allowing changes to the event subscriptions or notification URL.
operationId: updateWebhook
security:
- main-auth:
- webhooks:write
requestBody:
required: true
content:
application/json:
schema:
type: object
minProperties: 1
properties:
url:
type: string
format: uri
description:
type: string
eventTypes:
$ref: '#/components/schemas/webhook-event-types'
enabled:
type: boolean
responses:
'200':
description: Successful operation
content:
application/hal+json:
schema:
$ref: '#/components/schemas/webhook'
examples:
Example Update Webhook Response:
$ref: '#/components/examples/webhook'
'400':
$ref: '#/components/responses/bad-request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not-found'
'500':
$ref: '#/components/responses/server-error'
components:
parameters:
subaccount-id:
in: query
name: subaccountId
required: false
schema:
type: string
format: uuid
example: 2fd4d402-b759-479c-87a6-58d85e345356
limit:
in: query
name: limit
description: Maximum number of items to return
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 25
example: 25
webhook-id:
in: path
name: webhookId
required: true
schema:
type: string
format: uuid
example: 3c750084-a60f-478c-ab91-c53567d11fac
cursor:
in: query
name: cursor
required: false
description: The cursor to use for pagination. Identifies your place on the list
schema:
type: string
format: byte
example: ZXhhbXBsZQ==
schemas:
webhook-event-types:
type: array
minItems: 1
items:
type: string
enum:
- cardsubscription.created
- cardsubscription.updated
- transaction.created
- transaction.updated
- transactionmessage.created
- networkbulkfeed.statechanged
- enrichment.merchant.created
- banklink.completed
- bankaccount.state_changed
- banktransaction.created
- banktransaction.deleted
- transaction.match.created
- transaction.match.deleted
webhook:
type: object
description: Astrada's Webhook resource.
properties:
_links:
type: object
required:
- self
properties:
self:
$ref: '#/components/schemas/link'
id:
type: string
format: uuid
url:
type: string
format: uri
description:
nullable: true
type: string
eventTypes:
$ref: '#/components/schemas/webhook-event-types'
subaccountId:
type: string
format: uuid
createdAt:
type: string
format: date-time
description: Date and time when this resource was created, in UTC, following ISO 8601 format.
updatedAt:
type: string
format: date-time
description: Date and time when this resource was last updated, in UTC, following ISO 8601 format.
enabled:
type: boolean
default: true
required:
- _links
- id
- url
- description
- eventTypes
- subaccountId
- createdAt
- updatedAt
link:
type: object
properties:
href:
type: string
templated:
type: boolean
type:
type: string
deprecation:
type: string
name:
type: string
profile:
type: string
title:
type: string
hreflang:
type: string
required:
- href
responses:
not-found:
description: The requested resource was not found on the server
content:
application/problem+json:
schema:
type: object
properties:
type:
type: string
instance:
type: string
detail:
type: string
title:
type: string
enum:
- Not Found
required:
- detail
- title
example:
title: Not Found
detail: The requested resource was not found on the server.
unauthorized:
description: Authentication credentials were either missing or incorrect
content:
application/problem+json:
schema:
type: object
properties:
detail:
type: string
title:
type: string
enum:
- Unauthorized
required:
- detail
- title
example:
title: Unauthorized
detail: Authentication credentials were either missing or incorrect.
forbidden:
description: Authentication credentials used do not have have permissions to perform the request
content:
application/problem+json:
schema:
type: object
properties:
detail:
type: string
title:
type: string
enum:
- Forbidden
required:
- detail
- title
example:
title: Forbidden
detail: You do not have permission to access the requested resource.
server-error:
description: The server encountered an unexpected condition that prevented it from fulfilling the request
content:
application/problem+json:
schema:
type: object
properties:
detail:
type: string
title:
type: string
enum:
- Internal Server Error
required:
- detail
- title
example:
title: Internal Server Error
detail: The server encountered an unexpected condition that prevented it from fulfilling the request.
bad-request:
description: The server cannot or will not process the request due to something that is perceived to be a client error
content:
application/problem+json:
schema:
type: object
properties:
detail:
type: string
title:
type: string
enum:
- Bad Request
errors:
type: array
items:
type: object
properties:
title:
type: string
detail:
type: string
required:
- title
- detail
required:
- detail
- title
examples:
Example Generic Bad Request Payload Response:
value:
title: Bad Request
detail: Request object failed validation.
Example Generic Bad Request Parameters Response:
value:
title: Bad Request
detail: Request parameters are invalid.
examples:
webhook:
description: Example of Webhook resource
value:
_links:
self:
href: /webhooks/3a45ba7f-8d8f-4f6a-86a5-a17ea0328241
id: 3a45ba7f-8d8f-4f6a-86a5-a17ea0328241
url: https://example-api.com/path
description: Example of Webhook description
eventTypes:
- transactionmessage.created
subaccountId: f297d659-c13d-4219-aeaa-e10a845140a5
createdAt: '2023-12-19T14:45:00Z'
updatedAt: '2023-12-19T14:45:00Z'
enabled: true
securitySchemes:
main-auth:
type: oauth2
flows:
implicit:
authorizationUrl: https://api.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token
refreshUrl: https://api.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token
scopes:
accounts:write: Accounts write resource
accounts:read: Accounts read resource
subaccounts:write: Subaccounts write resource
subaccounts:read: Subaccounts read resource
card-connector-data-links:write: card-connector-data-link resource
card-connector-consents:read: Card Consent read resource
card-connector-consents:write: Card Consent write resource
webhooks:read: Read Webhook resources
webhooks:write: Write Webhook resources
card-subscriptions:write: Create card subscription
card-subscriptions:read: Read card subscription
card-verifications:write: Create card verification
card-verifications:read: Read Card verification
cards:read: Read Card resources
cardholder:read: Read Cardholder resources
cardholder:write: Write Cardholder resources
transactions:read: Read Transaction resources
transaction-messages:read: Read Transaction Message resources
network-bulk-feeds:read: Read network bulk feed
network-bulk-feeds:write: Write network bulk feed
network-links:write: Write network link
enrollment-methods:write: Write enrollment methods
simulation:write: Write sandbox simulations
banking:read: Read banking resources
banking:write: Write banking resources
banking:admin: Admin banking operations
appstore:enrollment:write: Enroll cards via the appstore B2C flow
appstore:cards:read: View enrolled cards in the appstore
appstore:transactions:read: View synced transactions in the appstore
appstore:transactions:sync: Trigger transaction sync in the appstore
appstore:sessions:read: Read appstore session state
appstore:sessions:write: Write or delete appstore session state
appstore:tokens:read: Read appstore stored tokens and connections
appstore:tokens:write: Write appstore stored tokens and connections
externalDocs:
description: Find out more about Astrada API.
url: https://docs.astrada.co/reference