Step 1: Configure your webhook endpoint

First, go to your developer dashboard > App > Webhooks.

Turn ON the Activity status.

🚧
Important:
You can turn OFF the webhook activity status at anytime, this will stop the sending of the events.

The webhook currently supports HTTPS and Amazon SQS provider methods.

You can choose to configure one method or both.
If both are well configured, the events will be sent to both.
If one provider fails and the other succeeds, the webhook will retry.
- It is recommend to check the x-webhook-correlation-id to ensure the same event is not processed multiple times.
- The x-webhook-correlation-id will be the same for both provider methods for the same event.

HTTPS

Webhook URL: Enter a valid URL to receive events. It must be a valid HTTPS URL.

🚧
Important:
For HTTP events, you will receive a POST request with the body containing the relevant data.

Amazon SQS

SQS Queue URL: Enter a valid queue URL to receive events.
AWS Access Key ID: An access key ID to a user or entity that can access this queue
AWS Secret Key: A secret key for the above user associated with the key ID.

Step 2: Subscribe to events

When setting up the webhooks you have the ability to choose to what events you want to subscribe.

You can also decide to subscribe to all.

Here is the full list of events you can subscribe to:

Event	Description
asset.minted	Triggered when an asset has been minted on the blockchain.
asset.transferred	Triggered when an asset has been transferred on the blockchain. This includes when an asset has been deposited.
asset.burned	Triggered when an asset has been burned on the blockchain.
asset.edited	Triggered when an asset has been edited on the blockchain.
reward.allocated	Triggered when rewards have been allocated on the blockchain
reward.claimed	Triggered when rewards have been claimed on the blockchain
reward.withdrawn	Triggered when a rewards contract has been terminated on the blockchain with funds withdrawn.
wallet.created	Triggered when a wallet has been created.

Asset events

asset.minted - triggered when an asset has been minted on the blockchain.
asset.transferred - triggered when an asset has been transferred on the blockchain.
asset.edited - triggered when an asset has been edited on the blockchain.
asset.burned - triggered when an asset has been burned on the blockchain.
🚧
Important:
If an asset has been burned outside of our API, we will attempt to detect it by querying various burn addresses. For more info, check the Burn asset API.

Assets will use the same event details, with the exception of the event and transaction_type.

Sample event details:

{
  "data": {
    "app": {
      "uid": "XXXXXXXXXXXX",
      "name": "App name567",
      "region": "EU",
      "environment": "Development"
    },
    "asset": {
      "uid": "xxxxxxxxxxxx",
      "name": "Dave Starbelly",
      "metadata": {
        "name": "Dave Starbelly",
        "image": "https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png",
        "original_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "org_image_url": "https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png",
        "attributes": [
          {
            "trait_type": "Base",
            "value": "Starfish"
          }
        ]
      },
      "token_id": 5,
      "asset_external_id": "505",
      "image_cid": null,
      "token_uri": "ipfs://QmNutummSoD6d6vDRiDYPDcugsZXP48qAfP2j5tNbLdXQv",
      "metadata_cid": "QmNutummSoD6d6vDRiDYPDcugsZXP48qAHPfj5tNbLdXQv",
      "mint_for_app_user": {
        "uid": "aa8fca1e-84be-4e5d-a031-055dcc633c46",
        "email": "[email protected]",
        "user_external_id": "74",
        "wallet_id": "xxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
        "wallet_address": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "wallet_backend_id": "dfns"
      }
    },
    "collection": {
      "uid": "xxxxxxxxxxxx",
      "name": "CollectionName",
      "type": "ERC721",
      "symbol": "",
      "website": null,
      "image_url": null,
      "description": "",
      "contract_address": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "transaction_log": {
      "type": "mint",
      "chain_id": 80001,
      "transaction_hash": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  },
  "event": "asset.minted",
  "sent_at": "2023-08-01T11:24:36.531141+00:00",
  "response": {
    "message_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status_code": 200
  },
  "x-app-uid": "XXXXXXXXXXXX",
  "x-webhook-attempt": "1",
  "x-webhook-correlation-id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Reward events

reward.allocated - triggered when rewards have been allocated on the blockchain.
reward.claimed - triggered when rewards has been claimed on the blockchain.
reward.withdrawn - triggered when a reward contract has been closed and withdrawn on the blockchain.

Rewards events will use the same base of event details with the exception of the event and transaction_type.

{
  "data": {
    "app": {
      "uid": "XXXXXXXXXXXX",
      "name": "App name567",
      "region": "EU",
      "environment": "Development"
    },
    "reward": {
      "name": "RewardName",
      "contract_address": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "uid": "xxxxxxxxxxxx",
      "description": "",
      "token_name": "Testnet ORI",
      "token_symbol": "TORI"
    },
    "transaction_log": {
      "transaction_hash": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "type": "mint",
      "chain_id": 80001
    }
  },
  "event": "reward.allocated",
  "sent_at": "2023-08-01T11:24:36.531141+00:00",
  "response": {
    "message_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status_code": 200
  },
  "x-app-uid": "XXXXXXXXXXXX",
  "x-webhook-attempt": "1",
  "x-webhook-correlation-id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

data will also include specific method category depending on the action, such as:

Allocation

    "allocation": {
      "uid": xxxxxxxxxxxx,
      "to_user_uid": xxxxxxxxxxxx,
      "amount": "1.23",
      "nonce": "nonce_1"
    },

Claim

    "claim": {
      "uid": xxxxxxxxxxxx,
      "from_user_uid": xxxxxxxxxxxx,
      "amount": "1.23",
      "to_address": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },

Withdraw

    "withdraw": {
      "to_address": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },

Sample event details:

{
  "data": {
    "app": {
      "uid": "XXXXXXXXXXXX",
      "name": "App name567",
      "region": "EU",
      "environment": "Development"
    },
    "asset": {
      "uid": "xxxxxxxxxxxx",
      "name": "Dave Starbelly",
      "metadata": {
        "name": "Dave Starbelly",
        "image": "https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png",
        "original_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "org_image_url": "https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png",
        "attributes": [
          {
            "trait_type": "Base",
            "value": "Starfish"
          }
        ]
      },
      "token_id": 5,
      "asset_external_id": "505",
      "image_cid": null,
      "token_uri": "ipfs://QmNutummSoD6d6vDRiDYPDcugsZXP48qAfP2j5tNbLdXQv",
      "metadata_cid": "QmNutummSoD6d6vDRiDYPDcugsZXP48qAHPfj5tNbLdXQv",
      "mint_for_app_user": {
        "uid": "aa8fca1e-84be-4e5d-a031-055dcc633c46",
        "email": "[email protected]",
        "user_external_id": "74",
        "wallet_id": "xxx-xxxx-xxxx-xxxxxxxxxxxxxxxx",
        "wallet_address": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "wallet_backend_id": "dfns"
      }
    },
    "collection": {
      "uid": "xxxxxxxxxxxx",
      "name": "CollectionName",
      "type": "ERC721",
      "symbol": "",
      "website": null,
      "image_url": null,
      "description": "",
      "contract_address": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "transaction_log": {
      "type": "mint",
      "chain_id": 80001,
      "transaction_hash": "0xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  },
  "event": "asset.minted",
  "sent_at": "2023-08-01T11:24:36.531141+00:00",
  "response": {
    "message_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status_code": 200
  },
  "x-app-uid": "XXXXXXXXXXXX",
  "x-webhook-attempt": "1",
  "x-webhook-correlation-id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Wallet event

wallet.created

This event is triggered when a wallet has been successfully created for a given app user and chain id.

Sample event details:

{
  "data": {
    "app": {
      "uid": "XXXXXXXXXXXX",
      "name": "MyApp",
      "region": "EU",
      "environment": "Development"
    },
    "app_user": {
      "uid": "xxxxxxxxxxxx",
      "client_id": "",
      "user_external_id": "",
      "email": "",
    },    
    "wallet": {
      "address": "0xxxxxxxxxxxx",
      "chain_id": 80002,
      "network": "Amoy",
    },    
  },
  "event": "wallet.created",
  "sent_at": "2023-08-07T16:33:46.897725+00:00",
  "response": {
    "message_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status_code": 200
  },
  "x-app-uid": "XXXXXXXXXXXX",
  "x-webhook-attempt": "1",
  "x-webhook-correlation-id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Step 1: Configure your webhook endpoint

🚧Important:

HTTPS

🚧Important:

Amazon SQS

Step 2: Subscribe to events

Asset events

🚧Important:

Reward events

Wallet event

wallet.created

🚧
Important:

🚧
Important:

🚧
Important: