Webhooks

Describes how to configure and use webhooks for the Token API.

Intro

Webhooks allow you to configure your endpoint URL and receive notifications for all your assets including ERC20 token contracts and ERC20 token mints. Configure webhooks from the NFT-API product section on the Developer Portal.

Token API: Receive notifications for all the successful and failed contract creations and token mints:

  • Contract deployment succeeded
  • Contract deployment failed
  • Token mint succeeded
  • Token mint failed

Retry Mechanism

If your endpoint URL is down, Venly will attempt to resend the notification message five times with an interval of 10 seconds to ensure delivery. After the last try, the message will be dropped since we don't store the webhook messages, they're not retrievable anymore.

In case your endpoint is down for more than 50 seconds and you don't receive the message:

Token API: You can call the check status endpoints using the unique id which is found in the response body for contract creation and token mints. Use the following endpoints:

  1. Check Token Contract Status
  2. Check Token Mint Status

How to configure webhooks?

📘

Webhooks for the Token API are configured from the NFT API page in the Portal. Meaning that configuring the webhooks in the NFT API page will send you notifications/messages for both the Token and NFT API.

If you have already configured webhooks for NFT API, you will automatically receive notifications/messages for the Token API.

  1. Head over to the Developer Portal.
  2. Under Configuration, click on the NFT API section.
  3. Click on Create webhook
Creating a new Webhook for NFT API

Creating a new Webhook for NFT API

  1. Add the relevant information:
    1. Description: Any sample description of the webhook.
    2. Endpoint (POST): The URL that accepts POST calls.
    3. Type: Select your preferred authentication type.
    4. Username/ Header name: Enter your custom username or header name (depends on the authentication type you selected.)
    5. Password/ API key: Enter your custom password or API key (depends on the authentication type you selected).
    6. Finally, click Create.

📘

Authentication is to be set up by you for your endpoint. This allows you to verify that the calls are coming from Venly.

Adding details for the Webhook

Adding details for the Webhook

  1. The webhook is created successfully!
Webhook created successfully

Webhook created successfully

  1. Click on the three dots to update or delete a webhook.
Update or Delete Webhook

Update or Delete Webhook

Successful Payload Examples

Following are the examples of payloads that you will receive for successful token mints and token contract creation.

📘

In the payloads you receieve, look for eventType and result.status.

Successful Token Mint

{
  "eventType": "ERC20_TOKEN_CREATION_SUCCEEDED",
  "result": {
    "id": "ea9a149f-cdad-44d6-ab0e-55a8a7490429",
    "createdOn": "2024-09-26T11:16:18.256375",
    "status": "SUCCEEDED",
    "transactionHash": "0x8a84df811b33f908cd31f6694ba621b9bef8e6617245970fad2d5627e8bdc1a2",
    "destination": {
      "address": "0x6296E346abb7Ecf72308c34de2F5a8888403a6b8",
      "amount": 450
    },
    "contract": {
      "address": "0xb1c62e4dc8dfab73c0fe12ba1736ddb976a485c0",
      "name": "Infinity Token",
      "symbol": "IFT",
      "maxSupply": 500,
      "burnable": true,
      "owner": "0x204EAca1F1E701EdC52FF9872D7DFc04a6481730",
      "type": "ERC_20"
    }
  }
}

Successful Token Contract Creation

{
  "eventType": "ERC20_CONTRACT_CREATION_SUCCEEDED",
  "result": {
    "id": "9e1c8b8b-9e7e-4ecd-98f9-98ab15c95651",
    "chain": "AVAC",
    "address": "0xb1c62e4dc8dfab73c0fe12ba1736ddb976a485c0",
    "name": "Infinity Token",
    "symbol": "IFT",
    "maxSupply": 500,
    "burnable": true,
    "owner": "0x204EAca1F1E701EdC52FF9872D7DFc04a6481730",
    "transactionHash": "0xa6c75281be7f1b5c543852f2fb6d40830398251ef27b7ceed54fd34afb6b74d4",
    "status": "SUCCEEDED"
  }
}

Failed Payload Examples

Following are the examples of payloads that you will receive for failed token mints and token contract creation.

Failed Token Mint

{
    "eventType": "ERC20_TOKEN_CREATION_FAILED",
    "result": {
        "id": "7bfd74a1-e514-4118-98d7-18b82751c4b2",
        "createdOn": "2024-06-17T14:08:24.795289",
        "status": "FAILED",
        "transactionHash": "string",
        "destination": {
            "address": "0xb1c62e4dc8dfab73c0fe12ba1736ddb976a485c0",
            "amount": 1
        },
        "contract": {
            "address": "0xb041536ab3b225a89e1a4fe2c601648dfa551145",
            "name": "Kindred cows - 1 square foot",
            "symbol": "DC62",
            "maxSupply": 0,
            "burnable": true,
            "owner": "string",
            "type": "ERC_20"
        }
    }
}

Failed Contract Creation

{
  "eventType": "ERC20_CONTRACT_CREATION_FAILED",
  "result": {
    "id": "bd442012-f0aa-4ed7-b770-2a13e0d965cd",
    "chain": "MATIC",
    "address": null,
    "name": "Infinity Token",
    "symbol": "IFT",
    "maxSupply": 500,
    "burnable": true,
    "owner": "0x204EAca1F1E701EdC52FF9872D7DFc04a6481730",
    "transactionHash": null,
    "status": "FAILED"
  }
}