Skip to main content

Webhook

Webhook Usage​

Webhooks allow you to send real-time notifications to registered endpoints, and Web3 Cloud uses HTTP to send these notifications as JSON payloads.

Register a Webhook Endpoint​

Register a Webhook Endpoint as an HTTP endpoint (URL) using RegisterWebhook in the Web3 Cloud API.

https://<your-key-manager-instance>/gincoinc.web3cloud.<your-chain>.keymanager.v1.KeyManagerService/RegisterWebhook

If Key Manager is not being used:

https://web3-cloud-testnet-prd.gincoapis.com/gincoinc.web3cloud.<your-chain>.gateway.v1.GatewayService/RegisterWebhook

Request (Notification) from Web3 Cloud​

Web3 Cloud makes a POST HTTP request and expect a HTTP response status 200.

Events sent via webhook are not guaranteed to be in sequence. Also, webhook events can be sent more than once. Therefore, endpoints receiving webhook notifications must be idempotent.

Web3 Cloud sends notifications when registered address involved in the following events:

  • ERC20, ERC721's Transfer event
  • ERC1155's TransferSingle, TransferBatch event

Plus, when registered address appearing in transaction or internal transaction's from or to field.

Example​

A ERC20 Transfer transaction. In this transaction, 25 LINK has been transferred from address 0x4281ecf07378ee595c564a59048801330f3084ee to address 0x6765c83e1fbb0dce280ed22b8a8db83e8f2bc297.

Assume from address (0x4281) and to address (0x6765) are both registered and a Webhook Endpoint (with confirmation 10) has been registered for the organization.

For from address, three notifications will be sent:

  1. When Web3 Cloud detects the pending transaction and finds from address in the transaction is registerd. confirmation in the webhook event will be 0.
  2. When the transaction is included in the block and from address in the transaction is registered. confirmation in the webhook event will be 10.
  3. When the transaction is included in the block and from address in the transaction's Transfer event log is registered. confirmation in the webhook event will be 10.

For to address, one notification will be sent:

  1. When the transaction is included in the block and to address in the transaction's Transfer event log is registered. confirmation in the webhook event will be 10.

Note​

  • Web3 Cloud also monitoring internal transactions. In this case, because it'a only a simple Transfer event, there is no extra internal transactions. However, if there are, Web3 Cloud will send the webhook event for each internal transaction if any registered address is involved.
  • Web3 Cloud will send the webhook event with confirmation 1 by default (besides for pending transaction) no matter what the confirmation is being set. As a result, for from address, there will be 5 webhook events in total and for to address, there will be 2 webhook event.
  • Web3 Cloud tries to finish balance update and token metadata update (for ERC721 and ERC1155) before sending webhook event and the whole process has a timeout of 5 minutes. If too many ERC721 or ERC1155 tokens are involved (for registered addresses) in one block, the process may take more than 5 minutes (because metadata update takes time). In such case, webhook event might not be sent or partially sent.

Request Schema​

API docs by Redocly

Webhook Request Schema

Download OpenAPI specification:Download

Webhook Request Schema

Request Body schema: application/json
webhook_id
string <uuidv4>

registered webhook id

webhook_endpoint
string

registered webhook endpoint

notification_type
string

NOTIFICATION_TYPE_EVM_TRANSACTION_UPDATED, NOTIFICATION_TYPE_SUBSTRATE_EVENT_UPDATED

EVMTransactionUpdated (object) or SubstrateEventUpdated (object)

Responses

Request samples

Content type
application/json
{
  • "webhook_id": "string",
  • "webhook_endpoint": "string",
  • "notification_type": "string",
  • "event": {
    }
}

Retry Policy​

If the Response Status Code is 3xx, 4xx, or 5xx, the webhook will be retried with increasing delay for each retry.

  • Minimum backoff duration: 30 seconds

  • Maximum backoff duration: 600 seconds

  • Testnet max delivery attempts: 5

  • Mainnet max delivery attempts: 30

If retries exceed 7 days, the message will be discarded.