Finix Payments Webhooks API
{'$ref': 'api-descriptions/tags/webhooks.md'}
OpenAPI Specification
openapi: 3.0.2
info:
title: Finix Authorizations Webhooks API
description:
$ref: api-descriptions/main.md
contact:
name: Finix
url: https://finix.com
email: support@finixpayments.com
version: '2022-02-01'
servers:
- description: Sandbox server to be used for testing and development
url: https://finix.sandbox-payments-api.com
security:
- BasicAuth: []
tags:
- name: Webhooks
description:
$ref: api-descriptions/tags/webhooks.md
paths:
/webhooks:
post:
tags:
- Webhooks
description: Create a `Webhook` to specify an endpoint where Finix can send events.
summary: Create a Webhook
operationId: createWebhook
requestBody:
$ref: '#/components/requestBodies/CreateWebhookRequest'
responses:
'201':
$ref: '#/components/responses/Webhook'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
'422':
$ref: '#/components/responses/Error422InvalidField'
x-java-method-name: create
parameters:
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)
x-python-method-name: create
get:
tags:
- Webhooks
description: Retrieve a list of `Webhooks`.
summary: List Webhooks
operationId: listWebhooks
parameters:
- $ref: '#/components/parameters/QueryLimit'
- $ref: '#/components/parameters/QueryAfterCursor'
- $ref: '#/components/parameters/QueryBeforeCursor'
responses:
'200':
$ref: '#/components/responses/WebhooksList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: list
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: curl
source: "curl \"https://finix.sandbox-payments-api.com/webhooks\" \\\n -H \"Finix-Version: 2022-02-01\" \\\n -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e\n"
x-python-method-name: list
x-returns-list: true
/webhooks/{webhook_id}:
parameters:
- description: ID of `Webhook` object.
required: true
in: path
name: webhook_id
schema:
type: string
get:
tags:
- Webhooks
description: Retrieve the details of a `Webhook`.
summary: Fetch a Webhook
operationId: getWebhook
responses:
'200':
$ref: '#/components/responses/Webhook'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: get
x-codeSamples:
- lang: cURL
label: curl
source: "curl \"https://finix.sandbox-payments-api.com/webhooks/WHN6HuqRqTV3mDCxoFLrRvP\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Finix-Version: 2022-02-01\" \\\n -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e\n"
x-python-method-name: get
put:
tags:
- Webhooks
description: 'Update an existing `Webhook`to:
- Disable or enable an endpoint URL to recieve webhook events.
- Add [authentication to a `Webhook`](/guides/developers/webhooks/#authenticating-webhooks).
- Filter the [webhook events sent to an endpoint URL](/guides/developers/webhooks/#webhook-event-filtering).'
summary: Update a Webhook
operationId: updateWebhook
requestBody:
$ref: '#/components/requestBodies/UpdateWebhookRequest'
responses:
'200':
$ref: '#/components/responses/Webhook'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: update
parameters:
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)
x-python-method-name: update
components:
responses:
Error422InvalidField:
description: Invalid field
content:
application/json:
schema:
$ref: '#/components/schemas/Error422InvalidFieldList'
ErrorUnprocessableEntity:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorGeneric'
Error406NotAcceptable:
description: Not Acceptable
content:
application/json:
schema:
$ref: '#/components/schemas/Error406NotAcceptable'
examples: {}
Webhook:
description: Single Webhook object
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
examples:
Webhook:
value:
id: WHg3ocwoCz9PgF4ncZTyArFJ
created_at: '2022-10-10T03:56:10.15Z'
updated_at: '2022-10-10T03:56:10.15Z'
application: APgPDQrLD52TYvqazjHJJchM
authentication:
type: NONE
enabled: true
enabled_events: []
previous_secret_expires_at: null
secret_signing_key: 3afb49c98ac08a67a58efa5580b24e5984bc36d7ebd404e875234f107deed108
url: https://eohzjuj2prziycz.m.pipedream.net
_links:
self:
href: http://finix.sandbox-payments-api.com/webhooks/WHg3ocwoCz9PgF4ncZTyArFJ
application:
href: http://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM
Filter Webhook Events:
value:
id: WHtPXJnAjmusyobzpmQZeHvJ
created_at: '2022-06-05T23:29:07.99Z'
updated_at: '2022-10-10T04:36:45.88Z'
application: APgPDQrLD52TYvqazjHJJchM
authentication:
type: NONE
enabled: false
enabled_events:
- entity: merchant
types:
- created
- underwritten
- entity: transfer
types:
- created
previous_secret_expires_at: null
url: https://eohzjuj2prziycz.m.pipedream.net
_links:
self:
href: http://finix.sandbox-payments-api.com/webhooks/WHtPXJnAjmusyobzpmQZeHvJ
application:
href: http://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM
headers:
finix-apiuser-role:
$ref: '#/components/headers/finix-apiuser-role'
date:
$ref: '#/components/headers/date'
x-request-id:
$ref: '#/components/headers/x-request-id'
ErrorNotFound:
description: Object does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/Error404NotFoundList'
ErrorForbidden403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error403ForbiddenList'
ErrorUnauthorized:
description: Authentication information is missing or invalid
content:
application/json:
schema:
$ref: '#/components/schemas/Error401Unauthorized'
WebhooksList:
description: List of Webhook objects
content:
application/json:
schema:
$ref: '#/components/schemas/WebhooksList'
examples:
List of Webhooks:
value:
_embedded:
webhooks:
- id: WHtbmULb3Y68oGfKWc9TLJnJ
created_at: '2022-09-27T18:40:29.20Z'
updated_at: '2022-09-27T18:40:29.39Z'
application: APgPDQrLD52TYvqazjHJJchM
authentication:
type: NONE
enabled: false
enabled_events: []
previous_secret_expires_at: null
url: https://example.com/
_links:
self:
href: http://finix.sandbox-payments-api.com/webhooks/WHtbmULb3Y68oGfKWc9TLJnJ
application:
href: http://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM
- id: WHmnVdiaimgD8aRTVvwuTZaj
created_at: '2022-09-27T18:38:56.81Z'
updated_at: '2022-09-27T18:38:57.03Z'
application: APgPDQrLD52TYvqazjHJJchM
authentication:
type: NONE
enabled: false
enabled_events: []
previous_secret_expires_at: null
url: https://example.com/
_links:
self:
href: http://finix.sandbox-payments-api.com/webhooks/WHmnVdiaimgD8aRTVvwuTZaj
application:
href: http://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM
_links:
self:
href: http://finix.sandbox-payments-api.com/notification/webhooks?offset=0&limit=20&sort=created_at,desc&sort=id,desc
next:
href: http://finix.sandbox-payments-api.com/notification/webhooks?offset=20&limit=20&sort=created_at,desc&sort=id,desc
last:
href: http://finix.sandbox-payments-api.com/notification/webhooks?offset=1360&limit=20&sort=created_at,desc&sort=id,desc
page:
offset: 0
limit: 20
count: 1197
headers:
finix-apiuser-role:
$ref: '#/components/headers/finix-apiuser-role'
date:
$ref: '#/components/headers/date'
x-request-id:
$ref: '#/components/headers/x-request-id'
schemas:
Error406NotAcceptable:
type: object
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
properties:
code:
type: string
enum:
- NOT_FOUND
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
properties:
source:
type: object
properties:
href:
type: string
title: ''
WebhookEnabledEvents:
title: WebhookEnabledEvents
x-stoplight:
id: ux7v2p72v0shw
type: array
description: A list of events the [webhook is explicitly enabled for](/guides/developers/webhooks/#webhook-event-filtering).
items:
type: object
properties:
entity:
type: string
description: The entity type for the enabled event. There can only be one enabled event object for a given entity.
types:
type: array
description: A list of event types you want to receive for the specified `entity`.
items:
type: string
Error401Unauthorized:
type: object
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
properties:
code:
type: string
enum:
- UNKNOWN
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
additionalProperties: true
properties:
self:
type: object
properties:
href:
type: string
source:
type: object
properties:
href:
type: string
ErrorGeneric:
type: object
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
properties:
code:
type: string
enum:
- FORBIDDEN
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
properties:
source:
type: object
properties:
href:
type: string
UpdateWebhookRequest:
title: UpdateWebhookRequest
x-stoplight:
id: 0jkq54c782t1w
type: object
properties:
enabled:
type: boolean
description: Set to false to disable `Webhooks`. Default value when created is true.
enabled_events:
$ref: '#/components/schemas/WebhookEnabledEvents'
url:
type: string
description: The HTTP or HTTPS url where the callbacks will be sent via POST request (max 120 characters).
PageCursor:
title: PageCursor
x-stoplight:
id: 8v9on8n2939z2
type: object
properties:
limit:
type: integer
description: The number of entries to return.
next_cursor:
type: string
description: The cursor to use for the next page of results.
nullable: true
description: Details the page that's returned.
Error403ForbiddenList:
type: object
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
properties:
code:
type: string
enum:
- FORBIDDEN
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
properties:
source:
type: object
properties:
href:
type: string
description: ''
title: ''
ListLinks:
title: ListLinks
additionalProperties: true
type: object
description: For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these `_links` to make your follow-up requests and quickly access relevant IDs.
properties:
next:
type: object
description: Link to the next page of entries.
properties:
href:
type: string
self:
type: object
description: Link to the resource that was used in the request.
properties:
href:
type: string
WebhooksList:
type: object
description: '`Webhook` resource.'
properties:
page:
$ref: '#/components/schemas/PageCursor'
_embedded:
type: object
description: List of `Webhook` objects.
properties:
webhooks:
type: array
minItems: 0
uniqueItems: true
description: '`Webhook` objects.'
items:
$ref: '#/components/schemas/Webhook'
_links:
$ref: '#/components/schemas/ListLinks'
Error404NotFoundList:
type: object
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
properties:
code:
type: string
enum:
- NOT_FOUND
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
properties:
source:
type: object
properties:
href:
type: string
Webhook:
type: object
properties:
id:
type: string
example: WHxxxxxxxxxxxxxxxxxx
description: The ID of the `Webhook` resource.
created_at:
$ref: '#/components/schemas/CreatedAt'
updated_at:
$ref: '#/components/schemas/UpdatedAt'
application:
type: string
description: The ID of the `Application` resource the `Webhook` was created under.
authentication:
type: object
description: The [authentication settings](/guides/developers/webhooks/#authenticating-webhooks) that are used to send webhook events.
properties:
type:
type: string
enum:
- NONE
- BASIC
- BEARER
description: 'The type of authentication the webhook will use:
- NONE: No authentication will be used.
- BASIC: Basic authentication.
- BEARER: Oauth2''s Bearer Token.'
enabled:
type: boolean
description: 'Details if the `Webhook` is enabled:<ul><li><strong>true</strong>: Events are being sent to the `url`.<li><strong>false</strong>: Events are not being sent.'
enabled_events:
$ref: '#/components/schemas/WebhookEnabledEvents'
previous_secret_expires_at:
type: string
description: The time when the previous `secret_signing_key` will expire. This is **null** when the webhook is initially created.
nullable: true
secret_signing_key:
type: string
description: The secret signing key that gets used to verify webhook events.
nullable: true
url:
type: string
description: The HTTP or HTTPS URL where callbacks (i.e. events) will be sent via POST request (max 120 characters).
_links:
type: object
description: For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these `_links` to make your follow-up requests and quickly access relevant IDs.
properties:
application:
type: object
description: Link to the `Application` the resource was created under.
properties:
href:
type: string
self:
type: object
description: Link to the resource that was used in the request.
properties:
href:
type: string
UpdatedAt:
type: string
title: UpdatedAt
format: date-time
description: Timestamp of when the object was last updated.
Error422InvalidFieldList:
type: object
description: Invalid field
title: ''
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
enum:
- INVALID_FIELD
field:
type: string
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
properties:
source:
type: object
properties:
href:
type: string
LogRef:
title: LogRef
type: object
properties:
logref:
type: string
CreatedAt:
type: string
title: CreatedAt
format: date-time
description: Timestamp of when the object was created.
CreateWebhookRequest:
title: WebhookCreate
type: object
properties:
authentication:
type: object
description: The [authentication settings](/guides/developers/webhooks/#authenticating-webhooks) that are used to send webhook events.
properties:
basic:
type: object
description: The basic authentication configuration. Null if basic is not being used.
properties:
username:
type: string
description: The username that will be used for basic authentication
password:
type: string
description: The password to be used for basic authentication.
bearer:
type: object
description: The bearer authentication configuration. Null if bearer is not being used.
properties:
token:
type: string
description: The string that Finix will send as the bearer token.
type:
type: string
enum:
- NONE
- BASIC
- BEARER
description: 'The type of authentication the webhook will use:
- **NONE**: No authentication will be used.
- **BASIC**: Basic authentication.
- **BEARER**: Oauth2''s Bearer Token.'
enabled:
type: boolean
description: Set to false to disable Webhooks. Default value when created is true.
enabled_events:
$ref: '#/components/schemas/WebhookEnabledEvents'
url:
type: string
description: The HTTP or HTTPS URL where callbacks (i.e. events) will be sent via POST request (max 120 characters).
maxLength: 120
example: https://example.com/event_handler
required:
- url
headers:
finix-apiuser-role:
schema:
type: string
enum:
- ROLE_ADMIN
- ROLE_PLATFORM
- ROLE_PARTNER
- ROLE_MERCHANT
x-request-id:
description: A unique ID for this specific API request attempt.
schema:
type: string
date:
schema:
type: string
parameters:
QueryBeforeCursor:
name: before_cursor
in: query
required: false
schema:
type: string
description: Return every resource created before the cursor value.
QueryAfterCursor:
name: after_cursor
in: query
required: false
schema:
type: string
description: Return every resource created after the cursor value.
QueryLimit:
description: The numbers of items to return.
example: 10
in: query
name: limit
schema:
type: integer
style: form
requestBodies:
UpdateWebhookRequest:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWebhookRequest'
examples:
Update Webhook:
value:
enabled: true
url: https://eohzjuj2prziycz.m.pipedream.net
Filter Webhook Events:
value:
enabled_events:
- entity: merchant
types:
- created
- underwritten
- entity: transfer
types:
- created
CreateWebhookRequest:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhookRequest'
examples:
Webhook:
value:
authentication:
type: NONE
url: https://example.com/event_handler
Webhook - Basic Authentication:
value:
authentication:
type: BASIC
basic:
username: basic-auth-username
password: basic-auth-password
url: https://example.com/event_handler
Webhook - Bearer Token Authentication:
value:
authentication:
type: BEARER
bearer:
token: U3VwZXIgc2VjcmV0IGVuY29kZWQgdG9rZW4=
enabled: true
url: https://example.com/event_handler
securitySchemes:
BasicAuth:
type: http
scheme: basic
description: ''
x-stoplight:
id: c6861590dda46
x-ignoredHeaderParameters:
- Accept
- finix-apiuser-role
- date
- x-request-id
x-tagGroups:
- name: MAIN RESOURCES
tags:
- Authorizations
- Compliance Forms
- Devices
- Disputes
- Fee Profiles
- Files
- Identities
- Instrument Updates
- Merchants
- Onboarding Forms
- Payment Instruments
- Settlements
- Split Transfers
- Transfers
- Users
- Webhooks
- name: CORE-PAYFAC RESOURCES
tags:
- Application Profiles
- Applications
- Balance Transfers
- Merchant Profiles
- Payout Profiles
- Verifications
- name: SUBSCRIPTION BILLING
tags:
- Subscription Schedules
- Subscription Amounts
- Subscription Enrollments
x-exclude-tags-from-libraries:
- Applications
- Application Profiles
- Fees
- Payment Instruments P2C
- Processors
- Review Queue
- Subscription Schedules
- Subscription Amounts
- Subscription Enrollments
- Users