thirdwebDocs
GitHub

Contract Subscriptions

Receive webhooks for any transaction log or receipt on any contract.

A log is an event emitted from a successfully executed transaction. Example: a burned NFT emits a Transfer OWNER -> 0x000... log.

A receipt contains onchain details for any transaction. This may be useful for tracking onchain failures (reverted executions).

Use cases

Your app may trigger an action when an onchain event occurs, such as:

  • ETH or an ERC20 currency is transferred to or from a wallet.
  • An token is minted from your NFT collection.
  • An token in your NFT collection is burned or transferred.
  • Metadata for an oracle contract is updated.

Manage Contract Subscriptions

Add a Contract Subscription

  • Navigate to the thirdweb dashboard.
  • Select Contract Subscriptions.
  • Select Add Contract Subscription.
  • Provide a webhook URL.

API reference: POST /contract-subscriptions/add

Remove a Contract Subscription

  • Navigate to the thirdweb dashboard.
  • Select Contract Subscriptions.
  • Select ... > Remove next to an existing subscription.

API reference: POST /contract-subscriptions/remove

Handling webhooks

Engine will call your webhook URL with event logs and transaction details for your specified contract(s).

Example webhook body

Verifying webhook signatures

See Webhooks for more information on managing webhooks and verifying webhook signatures.

FAQ

How do I receive multiple webhooks for the same contract address?

Add multiple Contract Subscriptions with different webhooks. Engine will process onchain data once to avoid duplicating work.

Can I query data via API?

Not at this time. This feature is on the future roadmap.

Do Contract Subscriptions backfill past data?

Not at this time. This feature is on the future roadmap.

Why should I use Contract Subscriptions instead of querying the blockchain directly?

Querying RPC nodes for onchain data is slow, unreliable, and costly at scale. RPCs have limits on the number of blocks that can be queried once. Even if your contract has low activity, your app must all blocks in your desired range to get accurate results.

Contract Subscriptions allow your app to query the onchain data you care about from database, which is faster, more reliable, and less costly.

How is Contract Subscriptions different than using event listeners with any web3 library?

Event listeners built into web3 libraries are appropriate to listen for real-time results without any persistence or resilience. If your backend request times out or your backend has an outage, event data is missed.

A Contract Subscription continuously poll the blockchain for logs and receipts since the last processed block and stores the results to database. Your app can rely on data to be stored eventually, even when unexpected issues with your backend, Engine, the RPC, or the blockchain occur.