CyberSource Create New Webhooks API
Create a new webhook connection
OpenAPI Specification
swagger: '2.0'
info:
description: All CyberSource API specs merged together. These are available at https://developer.cybersource.com/api/reference/api-reference.html
version: 0.0.1
title: CyberSource Merged Spec bankAccountValidation Create New Webhooks API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: Create New Webhooks
description: 'Create a new webhook connection
'
paths:
/kms/egress/v2/keys-sym:
post:
tags:
- Create New Webhooks
summary: Create Webhook Security Keys
description: 'Create security keys that CyberSource will use internally to connect to your servers and validate messages using a digital signature.
Select the CREATE example for CyberSource to generate the key on our server and maintain it for you as well. Remember to save the key in the API response, so that you can use it to validate messages later.
'
operationId: saveSymEgressKey
parameters:
- name: v-c-correlation-id
in: header
description: A globally unique id associated with your request
type: string
pattern: ^[A-Za-z0-9\.\-_:]+$
minLength: 2
maxLength: 100
- name: v-c-sender-organization-id
in: header
description: Sender organization id
type: string
pattern: ^[A-Za-z0-9\-_]+$
minLength: 2
maxLength: 100
- name: v-c-permissions
in: header
description: Encoded user permissions returned by the CGK, for the entity user who initiated the boarding
type: string
- name: SaveSymEgressKey
in: body
description: Provide egress Symmetric key information to save (create or store or refresh)
schema:
type: object
properties:
clientReferenceInformation:
type: object
description: Object for client references.
properties:
code:
type: string
maxLength: 50
description: 'Client generated order reference or tracking number. CyberSource recommends that you send a unique value for each
transaction so that you can perform meaningful searches for the transaction.
'
clientRequestAction:
type: string
description: 'Client request action.
'
keyInformation:
type: object
description: 'Egress Key Information Request
'
properties:
provider:
type: string
description: 'Provider name
'
tenant:
type: string
description: 'Tenant name
'
keyType:
type: string
description: 'Type of the key
'
organizationId:
type: string
description: 'Organization Id
'
clientKeyId:
type: string
description: 'Client key Id
'
keyId:
type: string
description: 'Key Serial Number
'
key:
type: string
description: 'Value of the key
'
status:
type: string
description: 'The status of the key
'
expiryDuration:
type: string
description: 'Key expiry duration in days
'
responses:
'201':
description: Successful Response
schema:
type: object
description: 'Egress Key Information Response
'
properties:
submitTimeUtc:
type: string
description: 'Time of request in UTC. Format: `YYYY-MM-DDThh:mm:ssZ`
Example `2016-08-11T22:47:57Z` equals August 11, 2016, at 22:47:57 (10:47:57 p.m.). The `T` separates the date and the
time. The `Z` indicates UTC.
'
status:
type: string
description: "The status of the submitted transaction.\nPossible values:\n - ACCEPTED\n"
clientReferenceInformation:
type: object
description: Object for client references.
properties:
code:
type: string
maxLength: 50
description: 'Client generated order reference or tracking number. CyberSource recommends that you send a unique value for each
transaction so that you can perform meaningful searches for the transaction.
'
keyInformation:
type: object
description: 'Egress Key Information
'
properties:
provider:
type: string
description: 'Provider name
'
tenant:
type: string
description: 'Tenant name
'
organizationId:
type: string
description: 'Organization Id
'
clientKeyId:
type: string
description: 'Client key Id
'
keyId:
type: string
description: 'Key Serial Number
'
key:
type: string
description: 'Value of the key
'
keyType:
type: string
description: 'Type of the key
'
status:
type: string
description: 'The status of the key
'
expirationDate:
type: string
description: 'The expiration time in UTC. `Format: YYYY-MM-DDThh:mm:ssZ`
Example 2016-08-11T22:47:57Z equals August 11, 2016, at 22:47:57 (10:47:57 p.m.). The T separates the date and the time. The Z indicates UTC.
'
message:
type: string
description: 'Message in case of failed key
'
errorInformation:
type: object
properties:
reason:
type: string
description: "The reason of the status.\nPossible values:\n - MISSING_FIELD\n - INVALID_DATA\n"
details:
type: array
items:
type: object
properties:
field:
type: string
description: This is the flattened JSON object field name/path that is either missing or invalid
reason:
type: string
description: "Possible reasons for the error.\nPossible values:\n - MISSING_FIELD\n - INVALID_DATA\n"
'400':
description: Bad Request
'401':
description: Unauthorized Request
'502':
description: Unexpected system error or system timeout
x-example:
example0:
summary: Create Webhook Symmetric Key
value:
clientRequestAction: CREATE
keyInformation:
provider: nrtd
tenant: <INSERT ORGANIZATION ID HERE>
keyType: sharedSecret
organizationId: <INSERT ORGANIZATION ID HERE>
example1:
summary: Store oAuth Credentials
value:
clientRequestAction: STORE
keyInformation:
provider: <INSERT ORGANIZATION ID HERE>
tenant: nrtd
keyType: oAuthClientCredentials
clientKeyId: client username
key: client secret
organizationId: <INSERT ORGANIZATION ID HERE>
expiryDuration: '365'
x-devcenter-metaData:
categoryTag: Webhooks
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-intro.html
/notification-subscriptions/v2/products/{organizationId}:
get:
tags:
- Create New Webhooks
summary: Find Products You Can Subscribe To
description: Retrieve a list of products and event types that your account is eligible for. These products and events are the ones that you may subscribe to in the next step of creating webhooks.
operationId: findProductsToSubscribe
parameters:
- name: organizationId
in: path
description: The Organization Identifier.
type: string
required: true
responses:
'200':
description: OK
schema:
type: array
items:
type: object
properties:
productId:
type: string
description: Product ID.
productName:
type: string
description: Product Name.
eventTypes:
type: array
items:
type: object
properties:
eventName:
type: string
displayName:
type: string
frequency:
type: integer
default: -1
timeSensitivity:
type: boolean
default: false
payloadEncryption:
type: boolean
default: false
example:
eventName: tms.networktoken.updated
payloadEncryption: true
'401':
description: Unauthorized
'404':
description: Not found
'500':
description: Server error
x-queryParameterDefaults:
organizationId: testrest
x-devcenter-metaData:
categoryTag: Webhooks
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-intro.html
/notification-subscriptions/v2/webhooks:
post:
tags:
- Create New Webhooks
summary: Create a New Webhook Subscription
description: 'Create a new webhook subscription. Before creating a webhook, ensure that a signature key has been created.
For the example "Create Webhook using oAuth with Client Credentials" - for clients who have more than one oAuth Provider and have different client secrets that they would like to config for a given webhook, they may do so by overriding the keyId inside security config of webhook subscription.
See the Developer Center examples section titled "Webhook Security - Create or Store Egress Symmetric Key - Store oAuth Credentials For Symmetric Key" to store these oAuth credentials that CYBS will need for oAuth.
For JWT authentication, attach your oAuth details to the webhook subscription. See the example "Create Webhook using oAuth with JWT"
'
parameters:
- name: createWebhook
in: body
description: The webhook payload
schema:
type: object
properties:
name:
type: string
description: Client friendly webhook name.
description:
type: string
description: Client friendly webhook description.
organizationId:
type: string
description: Organization Identifier (OrgId) or Merchant Identifier (MID).
products:
type: array
description: To see the valid productId and eventTypes, call the "Create and Manage Webhooks - Retrieve a list of event types" endpoint.
items:
type: object
properties:
productId:
type: string
description: Product ID.
eventTypes:
type: array
items:
type: string
description: Array of the different events for a given product id.
webhookUrl:
type: string
description: The client's endpoint (URL) to receive webhooks.
healthCheckUrl:
type: string
description: 'The client''s health check endpoint (URL). If the user does not provide the health check URL, it is the user''s responsibility to re-activate the webhook if it is deactivated by calling the test endpoint.
'
retryPolicy:
type: object
description: 'Retry policy for the individual webhooks that are a part of your subscription. If a message fails to deliver, it will execute through this retry policy.
Automatic suspend and resume:
If you experience downtime and have `deactivateFlag = true` any new messages will be held in a "SUSPENDED" status.
When your healthCheckUrl returns healthy again, the subscription will automatically be re-enabled and your messages will be sent.
We will ping your healthCheckUrl routinely using a POST call with an empty payload to check availability.
If your endpoint returns an unhealthy status of != 200, we will check the healthCheckUrl at a more frequent rate until it is healthy again.
If you experience downtime and have `deactivateFlag = false` and your message exhausts all retry attempts the message will go to a "FAILED" status.
Support will be notified and will reach out to suggest you execute the "REPLAY" endpoint at a later date when your server is healthy.
Reference the below values for formulas and calculations related to the frequency of retries depending on algorithm and configuration.
'
properties:
algorithm:
type: string
default: ARITHMETIC
description: 'This is used to calculate the Retry Sequence.
Sample calculations using firstRetry=10, interval=30, maxNumberOfRetries=3
Arithmetic = a+r(n-1)
Retry 1 - 10 minutes
Retry 2 - 10+30x1 = 40 minutes
Retry 3 - 10+30x2 = 70 minutes
Geometric = ar^(n-1)
Retry 1 - 10 minutes
Retry 2 - 10x30^1 = 300 minutes
Retry 3 - 10x30^2 = 9,000 minutes
'
firstRetry:
type: integer
description: When to initiate first retry, after the initial call failed. (in mins).
default: 1
interval:
type: integer
description: The interval between retries (in mins).
default: 1
numberOfRetries:
type: integer
description: The number of retries per sequence.
default: 3
deactivateFlag:
type: string
description: 'Deactivate the subscription if your retries fail to deliver.
If this is set to `true`, the automatic suspend and resume feature will occur.
This would prevent new webhooks from attempting to deliver and to queue up until your healthCheckUrl returns 200 again, then all messages will be sent.
If this is set to `false`, new individual messages will continue to retry and exhaust all failures, but the subscription will stay active.
'
repeatSequenceCount:
type: integer
description: 'The number of times to repeat the complete retry sequence.
0 => don''t repeat the retry sequence
1 => repeat the retry sequence once (R1, R2, R3)+ (R1, R2, R3)
2 => repeat the retry sequence twice (R1, R2, R3) + (R1, R2, R3) + (R1, R2, R3)
'
default: 0
repeatSequenceWaitTime:
type: integer
description: 'The time to wait to before repeating the complete retry sequence.
Amount of time to wait between each sequence.
Sample calculation using repeatSequenceWaitTime=10
(R1, R2, R3) + (10) + (R1, R2, R3) + (10) + (R1, R2, R3)
'
default: 0
additionalAttributes:
description: Additional data, if any.
type: array
items:
type: object
additionalProperties:
type: string
notificationScope:
type: string
description: "The webhook scope. 1. SELF The Webhook is used to deliver webhooks for only this Organization (or Merchant). 2. DESCENDANTS The Webhook is used to deliver webhooks for this Organization and its children. This field is optional. \n \nPossible values:\n- SELF\n- DESCENDANTS"
default: DESCENDANTS
securityPolicy:
type: object
description: The security option to authenticate with your API or client server.
properties:
securityType:
type: string
description: "Security Policy of the client server. \nPossible values:\n- key\n- oAuth\n- oAuth_JWT"
config:
description: Optional configuration object for if your API or server requires oAuth for an incoming webhook.
type: object
properties:
oAuthURL:
type: string
description: Client direct endpoint to the oAuth server.
oAuthTokenType:
type: string
description: "Token type for the oAuth config. \nPossible values:\n- Bearer"
additionalConfig:
description: Additional, free form configuration data.
type: object
properties:
aud:
type: string
client_id:
type: string
keyId:
type: string
scope:
type: string
produces:
- application/json;charset=utf-8
consumes:
- application/json;charset=utf-8
responses:
'201':
description: Created
schema:
type: object
properties:
webhookId:
type: string
description: Webhook Id. This is generated by the server.
organizationId:
type: string
description: Organization ID.
products:
type: array
items:
type: object
properties:
productId:
type: string
description: Product ID.
eventTypes:
type: array
items:
type: string
description: Event types within the product that you would like subscriptions for.
example:
productId: tokenManagement
eventTypes:
- tms.networktoken.provisioned
- tms.networktoken.updated
- tms.networktoken.binding
- tms.accountupdater.enrollment
- tms.accountupdater.update
webhookUrl:
type: string
description: The client's endpoint (URL) to receive webhooks.
healthCheckUrl:
type: string
description: The client's health check endpoint (URL).
status:
type: string
description: Webhook status.
default: INACTIVE
name:
type: string
description: Client friendly webhook name.
description:
type: string
description: Client friendly webhook description.
retryPolicy:
type: object
description: 'Retry policy for the individual webhooks that are a part of your subscription. If a message fails to deliver, it will execute through this retry policy.
Automatic suspend and resume:
If you experience downtime and have `deactivateFlag = true` any new messages will be held in a "SUSPENDED" status.
When your healthCheckUrl returns healthy again, the subscription will automatically be re-enabled and your messages will be sent.
We will ping your healthCheckUrl routinely using a POST call with an empty payload to check availability.
If your endpoint returns an unhealthy status of != 200, we will check the healthCheckUrl at a more frequent rate until it is healthy again.
If you experience downtime and have `deactivateFlag = false` and your message exhausts all retry attempts the message will go to a "FAILED" status.
Support will be notified and will reach out to suggest you execute the "REPLAY" endpoint at a later date when your server is healthy.
Reference the below values for formulas and calculations related to the frequency of retries depending on algorithm and configuration.
'
properties:
algorithm:
type: string
default: ARITHMETIC
description: 'This is used to calculate the Retry Sequence.
Sample calculations using firstRetry=10, interval=30, maxNumberOfRetries=3
Arithmetic = a+r(n-1)
Retry 1 - 10 minutes
Retry 2 - 10+30x1 = 40 minutes
Retry 3 - 10+30x2 = 70 minutes
Geometric = ar^(n-1)
Retry 1 - 10 minutes
Retry 2 - 10x30^1 = 300 minutes
Retry 3 - 10x30^2 = 9,000 minutes
'
firstRetry:
type: integer
description: When to initiate first retry, after the initial call failed. (in mins).
default: 1
interval:
type: integer
description: The interval between retries (in mins).
default: 1
numberOfRetries:
type: integer
description: The number of retries per sequence.
default: 3
deactivateFlag:
type: string
description: 'Deactivate the subscription if your retries fail to deliver.
If this is set to `true`, the automatic suspend and resume feature will occur.
This would prevent new webhooks from attempting to deliver and to queue up until your healthCheckUrl returns 200 again, then all messages will be sent.
If this is set to `false`, new individual messages will continue to retry and exhaust all failures, but the subscription will stay active.
'
repeatSequenceCount:
type: integer
description: 'The number of times to repeat the complete retry sequence.
0 => don''t repeat the retry sequence
1 => repeat the retry sequence once (R1, R2, R3)+ (R1, R2, R3)
2 => repeat the retry sequence twice (R1, R2, R3) + (R1, R2, R3) + (R1, R2, R3)
'
default: 0
repeatSequenceWaitTime:
type: integer
description: 'The time to wait to before repeating the complete retry sequence.
Amount of time to wait between each sequence.
Sample calculation using repeatSequenceWaitTime=10
(R1, R2, R3) + (10) + (R1, R2, R3) + (10) + (R1, R2, R3)
'
default: 0
additionalAttributes:
description: Additional data, if any.
type: array
items:
type: object
additionalProperties:
type: string
securityPolicy:
type: object
description: The security option to authenticate with your API or client server.
properties:
securityType:
type: string
description: "Security Policy of the client server. \nPossible values:\n- key\n- oAuth\n- oAuth_JWT"
config:
description: Optional configuration object for if your API or server requires oAuth for an incoming webhook.
type: object
properties:
oAuthURL:
type: string
description: Client direct endpoint to the oAuth server.
oAuthTokenType:
type: string
description: "Token type for the oAuth config. \nPossible values:\n- Bearer"
additionalConfig:
description: Additional, free form configuration data.
type: object
properties:
aud:
type: string
client_id:
type: string
keyId:
type: string
scope:
type: string
createdOn:
type: string
description: Date on which webhook was created/registered.
notificationScope:
type: string
description: "The webhook scope. 1. SELF The Webhook is used to deliver webhooks for only this Organization (or Merchant). 2. DESCENDANTS The Webhook is used to deliver webhooks for this Organization and its children. This field is optional. \n \nPossible values:\n- SELF\n- DESCENDANTS"
default: DESCENDANTS
example:
webhookId: b555a545-58a9-47c7-aef9-10a8e17f201a
organizationId: <INSERT ORGANIZATION ID HERE>
products:
- productId: tokenManagement
eventTypes:
- tms.networktoken.provisioned
- tms.networktoken.updated
- tms.networktoken.binding
- tms.accountupdater.enrollment
- tms.accountupdater.update
- productId: invoicing
eventTypes:
- invoicing.customer.invoice.paid
- invoicing.customer.invoice.send
webhookUrl: https://example.com:443/cybs
healthCheckUrl: https://example.com:443/cybs/healthcheck
status: INACTIVE
name: My Webhook Subscription
description: Webhook Subscription
retryPolicy:
algorithm: Geometric
firstRetry: 3
interval: 5
numberOfRetries: 4
deactivateFlag: true
securityPolicy:
securityType: oAuth
config:
oAuthURL: https://MyWebhookServer.com:8443/oAuthToken
oAuthTokenType: Bearer
additionalConfig:
aud: idp.api.myServer.com
client_id: 650538A1-7AB0-AD3A-51AB-932ABC57AD70
keyId: y-daaaAVyF0176M7-eAZ34pR9Ts
scope: merchantacq:rte:write
createdOn: '2021-02-25T23:25:11.000Z'
notificationScope: SELF
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Server error
x-example:
example0:
summary: Create Token Management Webhook
value:
name: My Custom Webhook
description: Sample Webhook from Developer Center
organizationId: <INSERT ORGANIZATION ID HERE>
products:
- productId: tokenManagement
eventTypes:
- tms.networktoken.provisioned
- tms.networktoken.updated
- tms.networktoken.binding
- tms.accountupdater.enrollment
- tms.accountupdater.update
webhookUrl: https://MyWebhookServer.com:8443/simulateClient
healthCheckUrl: https://MyWebhookServer.com:8443/simulateClientHealthCheck
retryPolicy:
algorithm: ARITHMETIC
firstRetry: 1
interval: 1
numberOfRetries: 3
deactivateFlag: 'false'
repeatSequenceCount: 0
repeatSequenceWaitTime: 0
securityPolicy:
securityType: KEY
example1:
summary: Create Recurring Billing Webhook
value:
name: My Custom Webhook
description: Sample Webhook from Developer Center
organizationId: <INSERT ORGANIZATION ID HERE>
products:
- productId: recurringBilling
eventTypes:
- rbs.subscriptions.charge.pre-notified
- rbs.subscriptions.charge.created
- rbs.subscriptions.charge.failed
webhookUrl: https://MyWebhookServer.com:8443/simulateClient
healthCheckUrl: https://MyWebhookServer.com:8443/simulateClientHealthCheck
retryPolicy:
algorithm: ARITHMETIC
firstRetry: 1
interval: 1
numberOfRetries: 3
deactivateFlag: 'false'
repeatSequenceCount: 0
repeatSequenceWaitTime: 0
securityPolicy:
securityType: KEY
example2:
summary: Create Invoicing Webhook
value:
name: My Custom Webhook
description: Sample Webhook from Developer Center
organizationId: <INSERT ORGANIZATION ID HERE>
products:
- productId: customerInvoicing
eventTypes:
- invoicing.customer.invoice.paid
- invoicing.customer.invoice.partialpayment
- invoicing.customer.invoice.cancel
- invoicing.customer.invoice.send
webhookUrl: https://MyWebhookServer.com:8443/simulateClient
healthCheckUrl: https://MyWebhookServer.com:8443/simulateClientHealthCheck
retryPolicy:
algorithm: ARITHMETIC
firstRetry: 1
interval: 1
numberOfRetries: 3
deactivateFlag: 'false'
repeatSequenceCount: 0
repeatSequenceWaitTime: 0
securityPolicy:
securityType: KEY
example3:
summary: Create Fraud Management Webhook
value:
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-create-new-webhooks-api-openapi.yml