Skip to main content

​
Overview

This guide outlines the steps to upgrade from Webhooks v1 to v2. Webhooks v1 will be deprecated on January 26th, 2026. Upgrade is designed to be seamless and instant. The primary change developers must make is modifying their codebases to accept the new v2 payload structure and updating their signature verification method.

​
How to Upgrade

1

Upgrade in CDP Portal

Migrating your webhook endpoints from v1 to v2 is an automatic process initiated from your developer portal.
  1. Navigate to the CDP Portal Webhooks page
  2. Click Upgrade on each v1 webhook you wish to migrate
  3. Upgrade will happen automatically. Your endpoint will begin receiving v2 payloads immediately.
If your v1 webhook monitors multiple contract addresses, the upgrade will automatically create a separate v2 subscription for each contract address. For example, a v1 webhook with 3 contracts will upgrade to 3 individual v2 subscriptions.
2

Update payload handling

Your webhook handler must be updated to parse the new v2 event structure. Below is an example of the v2 payload:
v2-payload-example.json
{
  "block_number": 38218578,
  "contract_address": "0x125E6687d4313864e53df431d5425969c15Eb2F",
  "event_name": "Transfer",
  "event_signature": "Transfer(address,address,uint256)",
  "log_index": 755,
  "network": "base-mainnet",
  "parameters": {
    "from": "0x0000000005f122FDDe066942195c10106d490486",
    "to": "0x0000000000000000000000000000000000000000",
    "value": "637064239"
  },
  "timestamp": "2025-11-15T17:08:24Z",
  "transaction_from": "0x0000000005f122FDDe066942195c10106d490486",
  "transaction_hash": "0xf1bdb4c4c48dd1c3c43b720890200f4d5a170c856b5c01ad1ab14e69ec",
  "transaction_to": "0x0000000005f122FDDe066942195c10106d490486"
}
All V2 webhooks include the block_number, timestamp, transaction_hash and network fields, as well as event-specific parameters
3

Update signature verification

Alongside the payload change, you must update your signature verification logic to be compatible with v2.Follow the Verify Signatures guide for a complete, step-by-step implementation of the new v2 verification logic.

​
Support and feedback

  • CDP Discord: Join #onchain-data for help and community support