Skip to main content
All CollectionsValue-Added Services (VAS)VAS Configuration Guides
sticky.io Webhook Service
sticky.io Webhook Service

The following article will showcase what webhook events are supported through the sticky.io Webhook service

Support avatar
Written by Support
Updated over a year ago

Introduction

The sticky.io webhook service enables merchants to post information about events to third-party systems using the sticky.io APIs. These webhooks are intended to be leveraged in relation to our chargeback services, including Ethoca Chargeback Alerts, Verifi CDRN, Verifi RDRs and sticky.io Representments. In the future, the scope of this service will be expanded into other aspects of the sticky.io service offerings.

The following article will showcase what webhook events are supported through the service.

Without further ado, let's begin!

Activating the sticky.io Webhook Service

To activate the sticky.io Webhook service, contact your sticky.io representative directly.

After activation by sticky.io personnel, you'll need to implement the necessary code to complete the integration process and in order to begin to receive and respond to the noted webhook events.

Receiving and Decoding Webhook Payloads

When receiving encrypted webhook payloads from sticky.io, the data is secured using the Advanced Encryption Standard (AES) algorithm, appearing as an unreadable string of alphanumeric characters. Importantly, the encrypted payload is base64 encoded. The encryption and decryption process relies on a secret KeyPhrase, defined by you during the activation process. This KeyPhrase, agreed upon between your server and sticky.io, is used by AES for transforming data into its encrypted and base64 encoded form, and back.

Upon reception, before initiating the decryption process, you must first base64 decode the payload. After base64 decoding, your server uses the KeyPhrase to decrypt the AES-encrypted data into its original format. Without the KeyPhrase, the encrypted and base64 encoded data remains secure and unintelligible, ensuring that payloads can only be accessed and understood by authorized parties. It’s vital to keep the KeyPhrase confidential to maintain the security and integrity of the transmitted data.

  1. Receive the base64 encoded and AES-encrypted payload from sticky.io.

  2. Base64 decode the payload to obtain the AES-encrypted data.

  3. Use the secret KeyPhrase to decrypt the AES-encrypted data into its original format.

Types of Webhook Events

There are four types of webhook events that are covered by the service. The webhook event types and the covered events are listed below:

Each event payload listed below that corresponds to each of these events contains essential data to help external systems respond effectively to these events.

Transaction

There are two transaction-related events covered by the webhook:

Transaction Refunded

This event is triggered when a transaction is refunded within the platform.

Below is a sample payload associated with the transaction.refunded event with in-line explanations of each pertinent parameter:

{
   "id":"ad83d0d7-375d-4c9a-8de0-e9c823f537f9",
   "object":{
      "orderId":"12345",
      "amount":1000,
      "amountRefunded":500,
      "initiated":"externally",
      "billingDetails":{
         "address":{
            "line_1":null,
            "line_2":null,
            "city":null,
            "state":null,
            "postal_code":null,
            "country":null
         },
         "email":null,
         "name":null,
         "lastName":null,
         "phone":null
      },
      "created":"2023-06-01 10:05:58.021",
      "currency":"usd",
      "customer":"12asde42"
   },
   "created":"2023-06-01 10:05:58.021",
   "triggeringEvent":"91496df6-52d9-4083-ab60-f3868efeef95",
   "correlationId":"cd201f6f-ccfb-40e1-a244-733925b24967"
}

Parameter

Description

id

UUID of the event

object.orderId

Order ID

object.amount

Total order amount in the smallest unit

object.amountRefunded

Amount refunded in the smallest unit

object.initiated

Enum {internally|externally}. Indicates whether the refund was performed by an external system, or by sticky (internal)

object.billingDetails.address.line_1

Line 1 of the address

object.billingDetails.address.line_2

Line 2 of the address

object.billingDetails.address.city

City of the address

object.billingDetails.address.state

State of the address

object.billingDetails.address.postal_code

Postal code of the address

object.billingDetails.address.country

Country of the address

object.billingDetails.email

Email associated with the billing details

object.billingDetails.name

First name of the customer

object.billingDetails.lastName

Last name of the customer

object.billingDetails.phone

Phone number of the customer

object.created

Timestamp of the Order creation

object.currency

Currency in which the transaction was made

object.customer

ID of the customer associated with this order

created

Timestamp of the event creation

triggeringEvent

If present, the previous event ID that triggered the current event

correlationId

An ID that links a group of events together

Transaction Voided

This event is triggered when a transaction is voided within the platform.

Below is a sample payload associated with the transaction.voided event with in-line explanations of each pertinent parameter:

{
  "id": "ad83d0d7-375d-4c9a-8de0-e9c823f537f9",
  "object": {
    "orderId": "12345",
    "amount": 1000,
    "initiated": "externally",
    "billingDetails": {
      "address": {
        "line_1": null,
        "line_2": null,
        "city": null,
        "state": null,
        "postal_code": null,
        "country": null
      },
      "email": null,
      "name": null,
      "lastName": null,
      "phone": null
    },
    "created": "2023-06-01 10:05:58.021",
    "currency": "usd",
    "customer": "12asde42"
  },
  "created": "2023-06-01 10:05:58.021",
  "triggeringEvent": "91496df6-52d9-4083-ab60-f3868efeef95",
  "correlationId": "cd201f6f-ccfb-40e1-a244-733925b24967"
}

Parameter

Description

id

UUID of the event

object.orderId

Order ID

object.amount

Total order amount in the smallest unit

object.initiated

Enum {internally|externally}. Indicates whether the refund was performed by an external system, or by sticky (internal)

object.billingDetails.address.line_1

Line 1 of the address

object.billingDetails.address.line_2

Line 2 of the address

object.billingDetails.address.city

City of the address

object.billingDetails.address.state

State of the address

object.billingDetails.address.postal_code

Postal code of the address

object.billingDetails.address.country

Country of the address

object.billingDetails.email

Email associated with the billing details

object.billingDetails.name

First name of the customer

object.billingDetails.lastName

Last name of the customer

object.billingDetails.phone

Phone number of the customer

object.created

Timestamp of the Order creation

object.currency

Currency in which the transaction was made

object.customer

ID of the customer associated with this order

created

Timestamp of the event creation

triggeringEvent

If present, the previous event ID that triggered the current event

correlationId

An ID that links a group of events together

Chargeback

There are four chargeback-related events covered by the webhook:

Chargeback Early Dispute Alert Created

This event is triggered when an alert is created from one of our Chargeback Services: Verifi RDR, Verifi CDRN, and/or Ethoca.

Below is an example webhook payload for the chargeback.early_dispute_alert.created event with in-line explanations for all pertinent parameters

{
   "id": "91496df6-52d9-4083-ab60-f3868efeef95",
   "object": {
      "providerName": "Verifi RDR",
      "alertDetails": {
      },
      "orderId": "12345",
      "potentialRelatedOrders": [ ]
   },
   "created": "2023-06-01 10:05:56.021",
   "correlationId": "cd201f6f-ccfb-40e1-a244-733925b24967"
}

In the context of the chargeback.early_dispute_alert.created webhook event:

  1. Successful Mapping: If the early dispute alert directly correlates with a specific order in your system, indicating a potential upcoming chargeback for that transaction, the orderId will be populated with the exact order ID value.

  2. Unmapped Alert: When an early dispute alert about a potential chargeback is triggered but doesn’t align with any known order in your system, the orderId is set to 0, signaling no associated transaction was found.

  3. Multiple Matches: If this early dispute alert could potentially relate to several orders and the system is uncertain about the precise correlation, the orderId is set to -1. In such cases, the payload will also provide a list of potential order IDs that might be related under the potentialRelatedOrders field, like so: "potentialRelatedOrders": ["12345", "23546", "85692"].

Chargeback Dispute Created

This event is triggered when a representment case is created from our Chargeback Representment Service.

Below is an example webhook payload for the chargeback.dispute.created event with in-line explanations for all pertinent parameters:

{
   "id": "91496df6-52d9-4083-ab60-f3868efeef95",
   "object": {
      "providerName": "sticky Chargebacks",
      "caseDetails": {
      },
      "orderId": "12345",
      "potentialRelatedOrders": ["12345", "23546", "85692"]
   },
   "created": "2023-06-01 10:05:58.021",
   "correlationId": "cd201f6f-ccfb-40e1-a244-733925b24967"
}

Chargeback Dispute Updated

This event is triggered when a representment case is updated from our Chargeback Representment Service.

Below is an example webhook payload for the chargeback.dispute.updated event with in-line explanations for all pertinent parameters:

{
   "id": "91496df6-52d9-4083-ab60-f3868efeef95",
   "object": {
      "providerName": "sticky Chargebacks",
      "caseDetails": {
      },
      "orderId": "12345",
      "updated": "2023-06-01 10:05:58.021",
   },
   "created": "2023-06-01 10:05:58.021",
   "correlationId": "cd201f6f-ccfb-40e1-a244-733925b24967"
}

Chargeback Dispute Closed

This event is triggered when a representment case is closed from our Chargeback Representment Service. This will indicate the outcome of whether or not you have won or lost the case.

Below is an example webhook payload for the chargeback.dispute.closed event with in-line explanations for all pertinent parameters:

{
   "id": "91496df6-52d9-4083-ab60-f3868efeef95",
   "object": {
      "providerName": "sticky Chargebacks",
      "caseDetails": {
      },
      "orderId": "12345"
   },
   "created": "2023-06-01 10:05:58.021",
   "correlationId": "cd201f6f-ccfb-40e1-a244-733925b24967"
}

Parameter

Description

id

UUID of the event

object.providerName

Name of the service that created the case [e.g., Verifi RDR, Verifi CDRN, sticky.io Chargebacks (Ethoca), sticky.io Chargebacks]

object.alertDetails

Full object with the alert detail (varies per provider)

object.orderId

Order ID that relates to this alert. If 0, unable to relate the alert to an order

object.potentialRelatedOrders

Order IDs potentially related to this alert. If present, orderId will be null

object.updated

Update timestamp of the case

created

Creation timestamp of the event

correlationId

An ID that links a group of events together

Subscription

Subscription Cancelled

This event is triggered when a subscription is cancelled.

Below is an example webhook payload for the subscription.cancelled event with in-line explanations for all pertinent parameters:

{
   "id": "46434f96-f8ec-4c47-ab9d-b4a2eb1b03c1",
   "object": {
      "id": "g12h3g2g31h",
      "orderId": "12345",
      "productId": 35
   },
   "created": "2023-06-01 10:05:58.021",
   "triggeringEvent": "91496df6-52d9-4083-ab60-f3868efeef95",
   "correlationId": "cd201f6f-ccfb-40e1-a244-733925b24967"
}

Parameter

Description

id

UUID of the event

object.id

Subscription ID

object.orderId

Order ID that is driving the subscription

object.productId

The ID of the product/bundle related to the subscription

created

Timestamp of the Event creation

triggeringEvent

If present, the previous event ID that triggered the current event

correlationId

An ID that links a group of events together

Blacklist

Blacklist Customer Added

This event is triggered when a customer is blacklisted.

Below is an example webhook payload for the blacklist.customer.added event with in-line explanations for all pertinent parameters:

{
   "id": "46434f96-f8ec-4c47-ab9d-b4a2eb1b03c1",
   "object": {
      "id": "g12h3g2g31h",
      "orderId": "",
      "paymentSource": {
         "id": "46434f96-f8ec-234f-asd3r-b4a2eb1b03c1",
         "first6": "420546",
         "last4": "1200",
         "expDate": "07/2031" 
      },
      "orderShippingDetails": {
         "name": "John",
         "lastName": "Doe",
         "address": {
            "line_1": null,
            "line_2": null,
            "city": null,
            "state": null,
            "postalCode": null,
            "country": null
         }
      },
      "billingAddress": {
         "line_1": null,
         "line_2": null,
         "city": null,
         "state": null,
         "postalCode": null,
         "country": null
      },
      "email": null,
      "name": "Jane",
      "lastName": "Doe",
      "phone": null,
      "blacklistedElements": ["email", "paymentSource"]
   },
   "created": "2023-06-01 10:05:58.021",
   "triggeringEvent": "91496df6-52d9-4083-ab60-f3868efeef95",
   "correlationId": "cd201f6f-ccfb-40e1-a244-733925b24967"
}

Parameter

Description

id

UUID of the event

object.id

Customer ID

object.orderId

Order ID through which the customer was blacklisted

object.paymentSource.id

Unique identifier of the payment source

object.paymentSource.first6

First 6 digits of the card

object.paymentSource.last4

Last 4 digits of the card

object.paymentSource.expDate

Expiration date of the card

object.orderShippingDetails.name

First name of the individual in the shipping details

object.orderShippingDetails.lastName

Last name of the individual in the shipping details

object.orderShippingDetails.address...

Address attributes related to shipping details

object.billingAddress...

Address attributes related to billing details

object.email

Email of the customer

object.name

First name of the customer

object.lastName

Last name of the customer

object.phone

Phone number of the customer

object.blacklistedElements

Elements for which the customer is blacklisted

created

Timestamp of the Event creation

triggeringEvent

If present, the previous event ID that triggered the current event

correlationId

An ID that links a group of events together

Disabling the sticky.io Webhook Service

Contact your sticky.io representative directly to unsubscribe from a given webhook or from the webhook service in its entirety.

Congratulations! You're now an expert on using the sticky.io webhook service.

Did this answer your question?