Changelog
Get API KeyStatusSupport
Back to All
added

Webhooks

March 13th, 2024 by Abdullah Baig

Introducing Webhooks for the Wallet-API and NFT-API. Configure webhooks and receive notifications for successful/failed transactions, contract creation, token-type creation, and token mints.

Webhooks

Introducing Webhooks that allow you to configure your endpoint URL and receive notifications for all your assets. Configure webhooks from the Wallet-API or NFT-API product section on the Developer Portal.

📘

For example, you can get notified when your transaction is successfully processed on the blockchain or if it fails.

Wallet-API: Receive notifications for all the successful and failed transactions carried out on all your wallets.

NFT-API: Receive notifications for all successful or failed contract creations, token-type creations, and token mints.

Features

1. Configure the endpoint (POST) to receive notifications for the following events:

📘

The endpoint you configure must be able to accept POST calls.

  • Wallet-API:
    • Transaction Succeeded
    • Transaction Failed
  • NFT-API:
    • Contract Creation Succeeded
    • Contract Creation Failed
    • Token-type creation Succeeded
    • Token-type creation Failed
    • Token Mint Succeeded
    • Token Mint Failed

2. Choose between two authentication methods for your endpoint:

📘

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

  1. Basic Authentication
  1. API Key

3. Retry Mechanism

If your endpoint URL is down, Venly will attempt to resend the notification message five times with an interval of 10 seconds in between 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:

  1. Wallet-API: You can call the check transaction status endpoint using the transactionHash of your specific transaction.
  2. NFT-API: You can call the check status endpoints using the unique id which is found in the response body for contract creation, token-type creation, and token mints as follows:
    1. Check Contract Status
    2. Check Token-type Status
    3. Check Token Mint Status

How to configure webhooks?

  1. Head over to the Developer Portal.
  2. Click on the product you want to configure webhooks for (Wallet API or NFT API)
  3. Scroll down and 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 endpoint URL that can accept 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.
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 transactions, contract creation, token-type creation, and token mints.

📘

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

Successful Transaction

{
  "eventType": "TRANSACTION_SUCCEEDED",
  "result": {
    "hash": "0xa2b91d7032c71f6810aeb075c17de25c44af7fe7f75ad5c58ffd853d31fad5cd",
    "status": "SUCCEEDED",
    "confirmations": 5,
    "blockHash": "0x35c20162d34a73fabbabcf5ed4d5f8585e3581f246a1a154ede1c01812cf405d",
    "blockNumber": 46095097,
    "hasReachedFinality": false,
    "chain": "MATIC",
    "nonce": 1,
    "gas": 21000,
    "gasUsed": 21000,
    "gasPrice": 30000000016,
    "logs": [
      {
        "logIndex": 0,
        "data": "0x000000000000000000000000000000000000000000000000002386f26fc10000000000000000000000000000000000000000000000000000015ecb81c114ff00000000000000000000000000000000000000000000000000016345785d8a0000000000000000000000000000000000000000000000000000013b448f5153ff000000000000000000000000000000000000000000000000000186cc6acd4b0000",
        "topics": [
          "0xe6497e3ee548a3372136af2fcb0696db31fc6cf20260707645068bd3fe97f3c4",
          "0x0000000000000000000000000000000000000000000000000000000000001010",
          "0x000000000000000000000000734dd2331ded9754ad8c39ddda8067a723cc36a9",
          "0x0000000000000000000000005e353f92bcaffcae9fd5c8d8ec530d63112f32fb"
        ]
      },
      {
        "logIndex": 1,
        "data": "0x00000000000000000000000000000000000000000000000000023cfb4e3560000000000000000000000000000000000000000000000000000161087d0f4f7f8000000000000000000000000000000000000000000000066cbb3ed45d1250c8ee000000000000000000000000000000000000000000000000015ecb81c11a1f8000000000000000000000000000000000000000000000066cbb411158608628ee",
        "topics": [
          "0x4dfe1bbbcf077ddc3e01291eea2d5c70c2b422b415d95645b9adcfd678cb1d63",
          "0x0000000000000000000000000000000000000000000000000000000000001010",
          "0x000000000000000000000000734dd2331ded9754ad8c39ddda8067a723cc36a9",
          "0x0000000000000000000000005082f249cdb2f2c1ee035e4f423c46ea2dab3ab1"
        ]
      }
    ],
    "from": "0x734dd2331ded9754ad8c39ddda8067a723cc36a9",
    "to": "0x5e353f92bcaffcae9fd5c8d8ec530d63112f32fb",
    "rawValue": 10000000000000000,
    "value": 0.01,
    "timestamp": "2024-02-19T10:48:33"
  }
}

Successful Token Mint

{
  "eventType": "TOKEN_CREATION_SUCCEEDED",
  "result": {
    "id": "3eab2361-5f0e-4122-8fe9-74b6f1fe0a88",
    "tokenId": 2,
    "status": "SUCCEEDED",
    "transactionHash": "0x407845cb6ce187a9f982aa00f4870851fe8877ef599e9d28084210373619dc14",
    "destination": {
      "address": "0x7312750DF4d2057b758a61C7017729c6Ec9bB3E9",
      "amount": 1
    },
    "metadata": {
      "name": "Test Token-type",
      "description": "Test token-type creation",
      "image": "https://play-lh.googleusercontent.com/ugkfJ2icapJi3vuS3WQfls6b8aM_YgcA_2Np18pg28vTLLbpeS2UEOWz9NvtB8oYGw=w240-h480-rw",
      "imagePreview": "https://play-lh.googleusercontent.com/ugkfJ2icapJi3vuS3WQfls6b8aM_YgcA_2Np18pg28vTLLbpeS2UEOWz9NvtB8oYGw=w240-h480-rw",
      "imageThumbnail": "https://play-lh.googleusercontent.com/ugkfJ2icapJi3vuS3WQfls6b8aM_YgcA_2Np18pg28vTLLbpeS2UEOWz9NvtB8oYGw=w240-h480-rw",
      "externalUrl": "www.venly.io",
      "external_url": "www.venly.io",
      "animationUrls": [],
      "attributes": [
        {
          "type": "stat",
          "name": "Health",
          "value": "98",
          "maxValue": "100",
          "displayType": "number",
          "display_type": "number",
          "traitType": "Health",
          "trait_type": "Health"
        },
        {
          "type": "system",
          "name": "tokenTypeId",
          "value": "1",
          "traitType": "Token Type ID",
          "trait_type": "Token Type ID"
        },
        {
          "type": "property",
          "name": "maxSupply",
          "value": "50",
          "traitType": "Max Supply",
          "trait_type": "Max Supply"
        },
        {
          "type": "property",
          "name": "mintNumber",
          "value": "1",
          "traitType": "Mint Number",
          "trait_type": "Mint Number"
        }
      ],
      "contract": {
        "address": "0xf5b11b4f458cc12a7989a146c5db2e7d500e2241",
        "name": "Test",
        "symbol": "TE",
        "image": "string",
        "imageUrl": "string",
        "image_url": "string",
        "description": "Testing",
        "externalLink": "www.venly.io",
        "external_link": "www.venly.io",
        "externalUrl": "www.venly.io",
        "external_url": "www.venly.io",
        "media": [],
        "type": "ERC_1155"
      },
      "fungible": false
    }
  }
}

Successful Token-type Creation

{
  "eventType": "TOKEN_TYPE_CREATION_SUCCEEDED",
  "result": {
    "id": "6852f668-2609-43fb-869e-a1de2e429ea9",
    "status": "SUCCEEDED",
    "transactionHash": "0x04778d3c6dfa2418a55fe53317520744b0e00100ff4453fd7892fa28f0f146fe",
    "tokenTypeId": 1,
    "metadata": {
      "name": "Test Token-type",
      "description": "Test token-type creation",
      "image": "https://play-lh.googleusercontent.com/ugkfJ2icapJi3vuS3WQfls6b8aM_YgcA_2Np18pg28vTLLbpeS2UEOWz9NvtB8oYGw=w240-h480-rw",
      "imagePreview": "https://play-lh.googleusercontent.com/ugkfJ2icapJi3vuS3WQfls6b8aM_YgcA_2Np18pg28vTLLbpeS2UEOWz9NvtB8oYGw=w240-h480-rw",
      "imageThumbnail": "https://play-lh.googleusercontent.com/ugkfJ2icapJi3vuS3WQfls6b8aM_YgcA_2Np18pg28vTLLbpeS2UEOWz9NvtB8oYGw=w240-h480-rw",
      "externalUrl": "www.venly.io",
      "external_url": "www.venly.io",
      "animationUrls": [],
      "attributes": [
        {
          "type": "stat",
          "name": "Health",
          "value": "98",
          "maxValue": "100",
          "displayType": "number",
          "display_type": "number",
          "traitType": "Health",
          "trait_type": "Health"
        },
        {
          "type": "system",
          "name": "tokenTypeId",
          "value": "1",
          "traitType": "Token Type ID",
          "trait_type": "Token Type ID"
        },
        {
          "type": "property",
          "name": "maxSupply",
          "value": "50",
          "traitType": "Max Supply",
          "trait_type": "Max Supply"
        }
      ],
      "contract": {
        "address": "0xf5b11b4f458cc12a7989a146c5db2e7d500e2241",
        "name": "Test",
        "symbol": "TE",
        "image": "string",
        "imageUrl": "string",
        "image_url": "string",
        "description": "Testing",
        "externalLink": "www.venly.io",
        "external_link": "www.venly.io",
        "externalUrl": "www.venly.io",
        "external_url": "www.venly.io",
        "media": [],
        "type": "ERC_1155"
      },
      "fungible": false
    }
  }
}

Successful Contract Creation

{
  "eventType": "CONTRACT_CREATION_SUCCEEDED",
  "result": {
    "name": "Test",
    "description": "Testing",
    "address": "0xf5b11b4f458cc12a7989a146c5db2e7d500e2241",
    "id": "a46bef57-c2b9-4eb7-8819-d0b38c445809",
    "secretType": "MATIC",
    "symbol": "TE",
    "externalUrl": "www.venly.io",
    "image": "string",
    "media": [],
    "transactionHash": "0xad5633541e106be988c30e51b2fcb2a997ac80610d095bfcf5c363d0df8fbea3",
    "status": "SUCCEEDED",
    "storage": {
      "type": "cloud",
      "location": "https://metadata-qa.arkane.network/metadata/contracts/10816"
    },
    "contractUri": "https://metadata-qa.arkane.network/metadata/contracts/10816",
    "external_link": "www.venly.io"
  }
}

Failed Payload Examples

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

Failed Transaction

{
    "eventType": "TRANSACTION_FAILED",
    "result":
    {
        "hash": "0x68561b2a59413c372a1fab4353b8904e7460726cf3437621b9237ef2ce82d718",
        "status": "FAILED",
        "confirmations": 10,
        "blockHash": "0x56b131735b33bc5502197d0416bbf3578efde89490d8a64aa5a463657ec3fbf0",
        "blockNumber": 46099161,
        "hasReachedFinality": false,
        "chain": "MATIC",
        "nonce": 25,
        "gas": 500000,
        "gasUsed": 26548,
        "gasPrice": 30000000019,
        "logs":
        [
            {
                "logIndex": 0,
                "data": "0x0000000000000000000000000000000000000000000000000002d45ba34957b4000000000000000000000000000000000000000000000000037cd7d78c65cf0000000000000000000000000000000000000000000000365eaa4ab987f7626320000000000000000000000000000000000000000000000000037a037be91c774c00000000000000000000000000000000000000000000365eaa4d8de39aabbad4",
                "topics":
                [
                    "0x4dfe1bbbcf077ddc3e01291eea2d5c70c2b422b415d95645b9adcfd678cb1d63",
                    "0x0000000000000000000000000000000000000000000000000000000000001010",
                    "0x00000000000000000000000096f06471cb1653617b778841106e40594f8d2105",
                    "0x000000000000000000000000be188d6641e8b680743a4815dfa0f6208038960f"
                ]
            }
        ],
        "from": "0x96f06471cb1653617b778841106e40594f8d2105",
        "to": "0xa89fc45fd76a4f46a48fcd0058ab28a3b9da55d5",
        "rawValue": 0,
        "value": 0.0,
        "timestamp": "2024-02-19T13:12:29"
    }
}

Failed Contract Creation

{
    "eventType": "CONTRACT_CREATION_FAILED",
    "result": {
        "name": "DAR-CONTR-69",
        "description": "DAR-CONTRACT-69",
        "id": "3fe78ac7-f8e9-4f60-acfe-8829df5bcca0",
        "secretType": "MATIC",
        "symbol": "DC62",
        "externalUrl": "https://en.wikipedia.org/wiki/Stick_figure",
        "image": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/coll_marvel.png",
        "media": [],
        "status": "FAILED",
        "owner": "0x075Eea524899C9dEF536D327A27Efce4fC9795ca",
        "storage": {
            "type": "cloud",
            "location": "https://metadata-staging.arkane.network/metadata/contracts/64653"
        },
        "contractUri": "https://metadata-staging.arkane.network/metadata/contracts/64653",
        "external_link": "https://en.wikipedia.org/wiki/Stick_figure"
    }
}

Failed Token-type Creation

{
    "eventType": "TOKEN_TYPE_CREATION_FAILED",
    "result":
    {
        "id": "e2abb6d1-26c6-422c-9643-b42c17c5c705",
        "status": "FAILED",
        "tokenTypeId": 34,
        "metadata":
        {
            "name": "string",
            "description": "PLEASE_FAIL",
            "image": "string",
            "imagePreview": "string",
            "imageThumbnail": "string",
            "backgroundColor": "string",
            "background_color": "string",
            "animationUrl": "string",
            "animation_url": "string",
            "externalUrl": "string",
            "external_url": "string",
            "animationUrls":
            [
                {
                    "type": "string",
                    "value": "string"
                }
            ],
            "attributes":
            [
                {
                    "type": "stat",
                    "name": "string",
                    "value": "string",
                    "maxValue": "string",
                    "displayType": "number",
                    "display_type": "number",
                    "traitType": "string",
                    "trait_type": "string"
                },
                {
                    "type": "system",
                    "name": "tokenTypeId",
                    "value": "34",
                    "traitType": "Token Type ID",
                    "trait_type": "Token Type ID"
                },
                {
                    "type": "property",
                    "name": "maxSupply",
                    "value": "1034534534634256245643564562456245645624562456245645624562546425645642562546245624564562645625",
                    "traitType": "Max Supply",
                    "trait_type": "Max Supply"
                }
            ],
            "contract":
            {
                "address": "0xde4cefc86a28c9a13d4a0846f322b9b5713b1a57",
                "name": "Kurt Remarque - updated",
                "symbol": "KURE",
                "image": "https://storage-qa.venly.io/applications/d047a0a7-bf8f-46e4-a3fd-561a94bfd114/matic.png",
                "imageUrl": "https://storage-qa.venly.io/applications/d047a0a7-bf8f-46e4-a3fd-561a94bfd114/matic.png",
                "image_url": "https://storage-qa.venly.io/applications/d047a0a7-bf8f-46e4-a3fd-561a94bfd114/matic.png",
                "description": "Modi qui id maiores.",
                "externalLink": "https://en.wikipedia.org/wiki/Stick_figure",
                "external_link": "https://en.wikipedia.org/wiki/Stick_figure",
                "externalUrl": "https://en.wikipedia.org/wiki/Stick_figure",
                "external_url": "https://en.wikipedia.org/wiki/Stick_figure",
                "media":
                [],
                "type": "ERC_1155"
            },
            "fungible": true
        },
        "errorMessage": "Could not prepare transaction. Bit size must be 8 bit aligned, and in range 0 < bitSize <= 256"
    }
}

Failed Token Mint

{
    "eventType": "TOKEN_CREATION_FAILED",
    "result": {
        "id": "f9754e80-ebb0-4cf9-8e82-c4191dd0b44f",
        "tokenId": 20,
        "status": "FAILED",
        "transactionHash": "0x98cfcd58282edc8a6d3f329a01a7350b7f148c31546b1a5c29e0311f339eb8e8",
        "destination": {
            "address": "0x6490d80c70990f27f50fee6189829cefe584998a",
            "amount": 1
        },
        "metadata": {
            "name": "DAR-TOKTYP-56",
            "description": "DAR-TOKEN-TYPE-56",
            "image": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/coll_marvel.png",
            "imagePreview": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/coll_marvel.png",
            "imageThumbnail": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/coll_marvel.png",
            "backgroundColor": "#021200",
            "background_color": "#021200",
            "animationUrl": "https://i.pinimg.com/originals/6a/34/9e/6a349ef34e90c467cf7bd5804de6b095.gif",
            "animation_url": "https://i.pinimg.com/originals/6a/34/9e/6a349ef34e90c467cf7bd5804de6b095.gif",
            "externalUrl": "https://en.wikipedia.org/wiki/Space_Chickens_in_Space",
            "external_url": "https://en.wikipedia.org/wiki/Space_Chickens_in_Space",
            "animationUrls": [
                {
                    "type": "GIF",
                    "value": "https://i.pinimg.com/originals/6a/34/9e/6a349ef34e90c467cf7bd5804de6b095.gif"
                }
            ],
            "attributes": [
                {
                    "type": "property",
                    "name": "Gold",
                    "value": "8",
                    "maxValue": "10",
                    "traitType": "Gold",
                    "trait_type": "Gold"
                },
                {
                    "type": "property",
                    "name": "Silver",
                    "value": "2",
                    "maxValue": "200",
                    "traitType": "Silver",
                    "trait_type": "Silver"
                },
                {
                    "type": "system",
                    "name": "tokenTypeId",
                    "value": "16",
                    "traitType": "Token Type ID",
                    "trait_type": "Token Type ID"
                },
                {
                    "type": "property",
                    "name": "maxSupply",
                    "value": "25",
                    "traitType": "Max Supply",
                    "trait_type": "Max Supply"
                }
            ],
            "contract": {
                "address": "0x6490d80c70990f27f50fee6189829cefe584998a",
                "name": "DAR-CONTR-49",
                "symbol": "DC42",
                "image": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/coll_marvel.png",
                "imageUrl": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/coll_marvel.png",
                "image_url": "https://storage-qa.venly.io/applications/1f64ded9-2a05-4824-b682-661023359357/coll_marvel.png",
                "description": "DAR-CONTRACT-49",
                "externalLink": "https://en.wikipedia.org/wiki/Stick_figure",
                "external_link": "https://en.wikipedia.org/wiki/Stick_figure",
                "externalUrl": "https://en.wikipedia.org/wiki/Stick_figure",
                "external_url": "https://en.wikipedia.org/wiki/Stick_figure",
                "media": [],
                "type": "ERC_1155"
            },
            "fungible": false
        },
        "errorMessage": "Transaction failed"
    }
}