We refreshed our doc site!

Bookmarked links may have changed

Read release notes

Web3 Services

Webhooks Flows

Common Considerations

All current and future implementations of notification messages have the following attributes:

NameTypeDescriptionSample
subscriptionIdStringId of the webhook subscription.80b9b08f-fd12-4f40-a3a6-51bad45cec51
notificationIdStringId for each even notification. This value is the same for retries.b3f2761f-6ae8-49f8-a730-6216aea08900
notificationTypeStringThe type of notificationtransactions.inbound
notification.versionint2

Current Implementations

This section lists models currently used by existing flows.

Transaction Flows

This section introduces the events that may occur with a transaction. 

Inbound Transactions

Confirmed

Confirmed transactions have been broadcast on the blockchain but have not yet reached the number of confirmations needed to be considered complete.

Confirmed Transaction Notification Payload:

JSON
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.inbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}

The payload will contain the information of a Transaction Object.

Completed

Completed transactions are settled transactions in which the needed number of blockchain confirmations has been met. Therefore the funds should be available in the destination account. 

Completed Transaction Notification Payload:

JSON
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.inbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}

The payload will contain the information of a Transaction Object.

Outbound Transactions

Queued

Queued transactions have been successfully initiated but have not yet been processed. 

Queued Transaction Notification Payload:

JSON
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.outbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}

The payload will contain the information of a Transaction Object.

Sent

Sent transactions are processed and sent to the blockchain node but have not yet been broadcast on-chain. 

Sent Transaction Notification Payload:

JSON
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.outbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2   
}

The payload will contain the information of a Transaction Object.

Confirmed

Confirmed transactions have been successfully broadcast on the blockchain but have not yet reached the number of confirmations needed to be considered complete. 

Confirmed Transaction Notification Payload:

JSON
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.outbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2   
}

The payload will contain the information of a Transaction Object.

Completed

Completed transactions are settled transactions in which the needed number of blockchain confirmations has been met. Therefore the funds should be available in the destination account. 

Completed Transaction Notification Payload:

JSON
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.outbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2  
}

The payload will contain the information of a Transaction Object.

Canceled

The following structure represents notifications for confirmed cancel requests: 

Canceled Transaction Notification Payload:

JSON
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.outbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}

The payload will contain the information of a Transaction Object.

Failed

A transaction might fail due to insufficient balance, failed challenge and so forth. A notification with the following structure is sent for failed transactions:

Failed Transaction Notification Payload:

JSON
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "transactions.outbound",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}

The payload will contain the information of a Transaction Object.

Challenge Flows

This section introduces the events that may occur with a challenge.

Complete

Complete challenges indicate that the operation has been successfully passed by the end-user. Therefore the associated action should be automatically initiated. 

Complete Challenge Notification Payload:

JSON
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "challenges.initialize",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}

The payload will contain the information of a Challenge Object.

Failed

Challenges can fail for reasons such as an incorrect pin being entered, the challenge expiring and so forth. A notification with the following structure is sent for failed challenges. This indicates that the operation needs to be re-initiated. 

Failed Challenge Notification Payload:

JSON
{
  "subscriptionId": "80b9b08f-fd12-4f40-a3a6-51bad45cec51",
  "notificationId": "b3f2761f-6ae8-49f8-a730-6216aea08900",
  "notificationType": "challenges.initialize",
  "notification": {
    "id": "",
    ...
  },
  "timestamp": "2023-06-29T15:05:33.135665781Z",
  "version": 2
}

The payload will contain the information of a Challenge Object.

Did this page help you?
© 2023-2024 Circle Technology Services, LLC. All rights reserved.