The CDP SDK allows you to create webhooks and receive onchain notifications within minutes. In this document, you will learn how to create a webhook, list created webhooks, update a webhook, and delete webhooks.

Our webhooks are in Alpha. Notification delivery is not yet guaranteed.

You can also configure webhooks via CDP Portal.

To learn more about webhook configuration options or event types, please follow this document.

​
What You’ll Learn

  • How to create a webhook
  • How to list webhooks
  • How to update a webhook
  • How to delete a webhook

​
Prerequisites

Before you get started, please follow this guide to install CDP SDK.

Webhooks on CDP SDK can be created at two levels:

  • External Address Webhook: This webhook can be used to track all supported events for any address.
  • Wallet Webhook: This webhook can be used to track all supported events all addresses in an API Wallet.

​
Authenticate

To get started, create a CDP API key and initialize the CDP SDK by passing your downloaded API key file.

You can authenticate with the Platform APIs by calling the configure method.

import { Coinbase } from "@coinbase/coinbase-sdk";
 Coinbase.configureFromJson({ filePath: '~/Downloads/cdp_api_key.json' });

This will allow you to authenticate with the Platform APIs.

​
External Address Webhook

​
Create

A webhook to track ERC20 transfer events can be created as follows:

Note that eventFilters param currently only supports one filter in the array check the SDK reference for more info on what filters are supported.

    // Import Webhook
    import { Webhook } from "@coinbase/coinbase-sdk";

    // be sure to update the uri to your webhook url
    //
    // signature_header is an optional field, it is used for x-webhook-signature header on callbacks
    // When your service receives a webhook callback, it needs to verify that the callback originated from Coinbase and has not been tampered with by any third parties.
    // The signature_header field allows you to specify a custom signature that will be included in the x-webhook-signature HTTP header of each callback request sent by Coinbase.
    let webhook = await Webhook.create({
    networkId: "base-mainnet",
    notificationUri: "https://example.com/callback",
    eventType: "erc20_transfer",
    eventFilters: [{ contract_address: "0x1234..." }], // eventFilters currently only supports one filter in the array
    signatureHeader: "optional-signature-string",
    });

    console.log(`Webhook successfully created: `, webhook.toString());

You can also create a webhook to track wallet activity as follows:

    import { Webhook } from "@coinbase/coinbase-sdk";

    let webhook = await Webhook.create({
    networkId: "base-mainnet",
    notificationUri: "https://example.com/callback",
    eventType: "wallet_activity",
    eventTypeFilter: { 
        addresses: ["0x1234..."],
        walletId: "wallet-id-you-want-to-track" // send empty string if you only want to track addresses
    }
    });

    console.log(`Webhook successfully created: `, webhook.toString());

​
List

You can view the list of webhooks that you’ve configured.

    // Return a list of webhooks
    let resp = await Webhook.list();
    let webhooks = resp.data;

    // Get the first webhook from the list of webhooks
    let webhook = webhooks[0]

    // Iterate over all webhooks created
    for (const wh in webhooks) {
        console.log(wh.toString());
    }

​
Update

You can change the notification URI of an external address webhook with the Update method.

    // Fetch the webhook to be updated.
    let webhooks = await Webhook.list();
    webhook = webhooks[0];
    webhook.update('http://example.com/callback2');

​
Delete

You can remove webhooks that are no longer needed.

    // Fetch the webhook to be deleted
    let webhooks = await Webhook.list();
    webhook = webhooks[0];
    await webhook.delete();

​
Wallet Webhook

You can create a webhook directly for an API Wallet, providing a convenient way to monitor its activities.

When you create a webhook for a wallet:

  • It is automatically configured to monitor the wallet’s activities.
  • It tracks all supported token types, including ERC20, ERC721, and ERC1155.
  • When new addresses are added to the wallet, the webhook automatically starts tracking them as well.

​
Create

    const wallet = await Wallet.create();
    let walletWebhook = await  wallet.createWebhook('http://abc.com')
    console.log(`Created webhook with ID: ${walletWebhook.id} for wallet: ${wallet.getId()}`);

​
Update

In addition to updating the notification URI, you can modify the list of addresses that a wallet activity webhook is tracking. A common use case is adding new addresses to the monitoring list. Key points to note:

  • Updates to the webhook use the PUT method, not PATCH. This means you must provide the complete list of addresses to monitor, including the existing ones, as the update replaces the entire list.
  • We cannot update the wallet ID of a wallet activity webhook, however when updating a webhook’s event type filter (where we specify the list of addresses), wallet ID is a required field. You may set it using the wallet ID of the wallet instance.
  • Updating a wallet activity webhook is only supported in Python and Node SDK.

Below are examples of how we can append new addresses to the existing list of addresses.

    const eventTypeFilter = walletWebhook.getEventTypeFilter();
    const addresses: string[] = [...eventTypeFilter?.addresses || []];

    addresses.push('0xNewAddress...');
    walletWebhook.update({eventTypeFilter: {addresses: addresses, walletId: eventTypeFilter.walletId}});