thirdwebDocs

Webhooks

Webhooks allow you to receive notifications when specific blockchain events or transactions occur. This enables you to automate workflows and keep your applications in sync with on-chain activity.

Data Delivery

Webhook events are collected and delivered in batches for optimal performance and reliability. This makes webhooks ideal for:

  • Tracking when specific blockchain events occur
  • Aggregating on-chain data
  • Building analytics and monitoring systems
  • Triggering downstream processes

Delivery Guarantees

Events are guaranteed to be delivered at least once. Your application should implement idempotency and deduplication logic using the unique event ID in the payload. Please note, events may occasionally be delivered out of order.

Performance Requirements

  • Your receiving endpoint must respond within 3 seconds
  • If your endpoint consistently fails to respond in time, the webhook will be automatically suspended
  • We recommend implementing a queue system if you need to perform time-consuming operations

Get started

Webhooks can be configured in the thirdweb dashboard (recommended) by creating a project or programmatically using the Insight API.

  • Creating a webhook requires a project. If you don't have a project yet, create one in the thirdweb dashboard and navigate to the Webhooks section.

  • Create a Webhook

    Select New Webhook and provide the following:

    • Name: A descriptive name for your webhook
    • Endpoint URL: The URL where you want to receive webhook notifications
    • Events: Select an event or transaction filter type:
      • Event: Triggered by specific blockchain events (e.g., token transfers, contract interactions)
      • Transaction: Triggered by transactions matching specific criteria (e.g., from/to address, value)
    Create Webhook

  • Configure Filters

    You can set up filters to narrow down the events or transactions that trigger the webhook.

    For EVENTS:

    • Chain IDs: Select the blockchain networks you want to monitor (e.g., Ethereum, Polygon)
    • Contract Addresses: Specify contract addresses to filter events related to specific contracts
    • Event Signatures: For event filters, you can specify event signatures to target specific events
    • ABI: For event filters, you can provide the ABI of the contract- providing the contract's address will usually automatically fetch the ABI.

    For TRANSACTION:

    • Chain IDs: Select the blockchain networks you want to monitor
    • From/To Addresses: Specify addresses to filter transactions by sender or recipient
    • Function Signatures: For transaction filters, you can specify function signatures to target specific contract interactions
    • ABI: For transaction filters, you can provide the ABI of the contract- providing the contract's address will usually automatically fetch the ABI.
    Create Filters

  • Test & Create Webhook

    After creating the webhook, you can test it by sending a sample event. This allows you to verify that your endpoint is correctly configured to receive and process webhook notifications.

    After successful testing, click "Create Webhook" to finalize the setup.

    Test Webhook