On This Page

Introduction to Webhooks

Webhooks are automated notifications generated by system events that occur in your organizations. You can create a webhook subscription and designate a URL to receive notifications when a sale status updates. By setting up automatic webhook notifications, you do not need to send check status requests to monitor a sale status.
Webhook notifications are only sent when a sale status changes.
IMPORTANT
This section only describes overview information about creating a webhook subscription. You must complete additional set-up tasks that are not described in this guide before you can create a webhook subscription. If you have not set up your system to support webhooks, see the
Webhooks Implementation Guide for the REST API
.
Notifications that contain sensitive, personally identifiable information (PII), such as account numbers, are sent using message-level encryption.
Transport Layer Security is required in order to ensure data integrity.

Endpoints

Send a POST request to one of these endpoints:
  • Test:
    POST
    https://apitest.cybersource.com
    /notification-subscriptions/v2/webhooks
  • Production:
    POST
    https://api.cybersource.com
    /notification-subscriptions/v2/webhooks
  • India Production:
    POST https://api.in.cybersource.com/notification-subscriptions/v2/webhooks

Notification Statuses

Webhook subscriptions send these notification statuses:
  • CANCELLED
    : The customer did not complete the checkout using the redirect URL.
  • FAILED
    : The sale request failed.
  • SETTLE_INITIATED
    : The customer completed checkout and PayTo Pay by Bank is processing the sale.
  • SETTLED
    : The sale is settled for the requested amount.

Test Your Webhook Requests

You can use the
Cybersource
 REST API Reference
 to send webhook related test requests. See the Create a Webhook section in the
Cybersource
 REST API Reference
.

Required Fields for Webhooks

name
organizationId
eventTypes
Set the value of this field to
payments.payments.updated
.
productId
Set the value of this field to
alternativePaymentMethods
.
securityPolicy.securityType
Set to
KEY
.
webhookUrl

Optional Fields for Webhooks

deactivateflag
Required if the
healthCheckUrl
 field is present.
Set to
true
 to automatically activate the subscription.
healthCheckUrl
Set to the health check URL. Required to auto-activate the subscription. If you do not include this field, the created subscription is inactive. An inactive subscription does not send notifications.
retryPolicy.deactivateFlag
retryPolicy.firstRetry
retryPolicy.interval
retryPolicy.numberOfRetries
retryPolicy.repeatSequenceCount
retryPolicy.repeatSequenceWaitTime

Example: Webhooks

Request
{
    "name": "My Custom Webhook",
    "description": "Sample Webhook from Developer Center",
    "organizationId": "paytotestapm003",
    "productId": "alternativePaymentMethods",
    "eventTypes": [
        "payments.payments.updated"
    ],
    "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient",
    "notificationScope": "SELF",
    "securityPolicy": {
        "securityType": "KEY",
        "proxyType": "external"
    }
}
Response to a Successful Request
{
  "organizationId": "paytotestapm003",
  "productId": "alternativePaymentMethods",
  "eventTypes": [
    "terminalManagement.assignment.update"
  ],
  "webhookId": "ddb9bced-c3e3-1b1d-e053-9c588e0a3c42",
  "name": "My Custom Webhook",
  "webhookUrl": "https://MyWebhookServer.com:443/simulateClient",
  "healthCheckUrl": "https://MyWebhookServer.com:443/simulateClientHealthCheck",
  "createdOn": "2022-04-28T15:39:56.928Z",
  "status": "ACTIVE",
  "description": "Sample Webhook from Developer Center",
  "securityPolicy": {
    "securityType": "KEY",
    "digitalSignatureEnabled": "yes"
  },
  "version": "3",
  "notificationScope": "SELF"
}
RELATED TO THIS PAGE