How to Get Real-Time Crypto Updates Without Polling (Webhook Guide)

Polling is best suited for on-demand queries, historical data, and standard lookups. But it is less efficient for real-time crypto updates like coin metadata changes, price-threshold alerts, and newly indexed token events. Your system keeps sending requests on a fixed schedule even when nothing has changed, which adds latency and keeps a server running 24/7 to detect market updates. As your application scales, this leads to more API requests, higher server load, and greater operational overhead. With Webhook, it removes that friction with an event-driven push mode. Instead of repeatedly checking for updates, your endpoint receives a signed HTTP POST whenever an event occurs.

By the end of this guide, you will understand how cryptocurrency webhooks work and how to build a webhook receiver, test, debug, and integrate real-time crypto events.

---

What Are Cryptocurrency Webhooks?

A cryptocurrency webhook, such as CoinGecko's webhook, is an event-driven HTTP callback that automatically pushes real-time notifications to an endpoint URL when a predefined crypto event occurs, eliminating the need to build your own polling and change-detection logic. These events can include coin metadata updates (name, symbol, logo, contract address, categories, or public notices), onchain activity, and price threshold alerts.

Today, CoinGecko API supports the cg.coin.info.updated event and triggers whenever a coin’s metadata changes. This helps your systems stay aligned with the latest coin data, from keeping token information accurate to surfacing important security-related updates.

Webhooks, REST, and WebSocket are the three data delivery methods in the CoinGecko API. Each serves a different purpose, and often complement each other in production systems. REST fetches data on demand, WebSocket streams ultra-low latency live prices and trades, and Webhooks notify your application when specific events occur.

---

Setting Up Your Webhook Endpoint in Python

In this section, you will set up a webhook receiver by generating a public HTTPS URL, creating it in the Developer Dashboard, and building a Python endpoint for webhook events. Before proceeding, choose the option that matches your setup to start receiving real-time crypto updates:

• You have a deployed server: Use your domain and skip to Step 2.
• You are prototyping locally: Follow the steps below to create a tunneling tool that exposes a public HTTPS URL

Step 1: Get a Public HTTPS URL for Your Endpoint

CoinGecko delivers events over HTTPS, so your webhook requires a publicly accessible URL. This guide uses Ngrok for simplicity. Alternatives such as Cloudflared and Localtunnel follow a similar approach.

1. Install Ngrok, then add your authtoken:

2. Start the tunnel on port 8080, which will be used by the Flask app:

3. Ngrok prints a forwarding URL, copy it and paste into the dashboard in the next step. While the localhost URL is where ngrok forwards traffic to your server.

Step 2: Create the Webhook in the Developer Dashboard

CoinGecko’s webhook feature is available on the Analyst plan and above. Each user can configure up to 5 webhooks, with 10 API credits charged per delivered event, and retry attempts are not charged API credits.

Go to the Developer Dashboard’s Webhook Section, click ‘Add Webhook’, and paste in the webhook endpoint URL. The detail view will then display a signing secret, which is a private key prefixed with whsec_. Your server uses this to verify that incoming requests are genuinely from CoinGecko.

Step 3: Create Your Project Files

Create a project folder with two files: requirements.txt lists the dependencies, and .env that stores the signing secret.

File: requirements.txt

Install with pip.

File: .env

Step 4: Verify the HMAC Signature

Before trusting a payload, verify its HMAC signature to confirm it was sent by CoinGecko. Your server should recompute the signature using your signing secret and compare it in constant time before accepting the request.

The request includes three security headers, x-cg-signature, x-cg-timestamp, and x-cg-event-id. The signature is an HMAC-SHA256 of a signing string built from the timestamp, the event ID, and the raw request body, joined with colons in the form {timestamp}:{event_id}:{raw_body}.

Step 5: Build the Receiver

For each incoming request, the receiver reads the raw body and CoinGecko headers, rejects requests with an expired timestamp (replay protection), verifies the HMAC signature, ignores duplicate events using event_id, parses the payload, and dispatches it to a handler.

Step 6: Run and Test

Start the server:

You should see Flask running on port 8080. If you are using a tunneling tool, your local application will receive the requests.

To test your endpoint, click “Send Test Event” in the dashboard. This validates the full webhook integration, including HTTPS connectivity, signature verification, payload parsing, and handler logic.

Here’s what a successful test delivery looks like:

---

How to Track Coin and Token Metadata Updates (Contract Address, Migrations & more)

CoinGecko’s cg.coin.info.updated webhook event triggers whenever a tracked metadata field on a coin changes and delivers the previous and new values in the payload.

Metadata changes can have meaningful market and operational impact. When CoinGecko reports updates related to unverified contracts or mintable supply, traders, security tools, and downstream platforms may respond quickly, with price movement often following soon after. Contract migrations can also fragment liquidity between old and new addresses, create phishing opportunities, and cause trades to be routed incorrectly when systems continue relying on stale contract data. Detecting these changes early helps platforms protect users, route trades accurately, and surface important market signals before broader market reaction takes place.

The table below breaks down the different types of metadata updates, followed by three real webhook delivery examples showing common patterns in how these changes appear in practice.

Alert When a Coin Is Added to a Category

When the categories field changes, your application can detect when a coin is added to or removed from a category and trigger downstream workflows.

Detect Coin Identity Changes (Name, Symbol, Web Slug)

Changes to name, symbol, or web_slug can be used to identify rebrands and update user-facing interfaces.

Monitor Public Security Notices & Risk Alerts

Updates to public_notices can be surfaced to users or routed to monitoring systems for review.

For the complete field list, refer to CoinGecko’s cg.coin.info.updated webhook event documentation for more information.

---

How Metadata Updates Power Your Applications

Once a metadata update is detected, it can be routed into downstream systems that power real-time operational workflows from alerts to backend processes such as link validation, token registry synchronization, and contract migration monitoring.

These updates enable systems to react instantly to changes in token data, instead of relying on manual checks or scheduled diffs. Common use cases include:

• Telegram bot: Alerts when a project publishes a security notice or triggers a contract migration, enabling faster response to risk events.
• Live market monitoring: Streams real-time changes in how a coin is classified and identified, keeping research workflows and watchlists in sync.
• Wallet or security system: Re-validates project links and contract addresses when they change, helping prevent stale or compromised metadata from being used.
• CEX & DEX operations teams: Receive instant updates when a tracked coin adds a new chain or migrates contracts, allowing immediate operational action.

The following examples illustrate how CoinGecko’s webhook can be used to power Telegram bot alerts and live market monitoring interfaces:

---

Handling Errors and Failed Deliveries

Most webhook issues appear as non-2xx responses in the dashboard's delivery logs or as requests that never reach your server. This section covers common development-time errors and CoinGecko's retry behavior for failed deliveries.

Common Webhook Errors

The dashboard log displays the HTTP status code returned by your server, which is often enough to identify most issues. These usually fall into a few common patterns:

401 Unauthorized: HMAC signature mismatch

Issue: Signing secret mismatch or HMAC computed from parsed JSON instead of raw body.

How to fix: Re-copy the secret from the dashboard and compute HMAC using {timestamp}:{event_id}:{raw_body}.

404: Endpoint Not Found

Issue: Dashboard URL does not match any server route. Common causes include typos, route changes, reverse proxy path modifications, or trailing-slash mismatches.

How to fix: Ensure the dashboard URL exactly matches the server route, including path and trailing slash.

5xx: Server Error

Issue: Handler error during webhook processing (e.g. malformed payload or missing fields), resulting in a 500 response. CoinGecko will retry delivery up to 14 times.

How to fix: Add error handling around parsing and processing. Log the raw request body for debugging. Return 2xx when the event is safely handled; use 5xx only when retry is intended.

Delivery Retries and Failure Handling

When an event delivery fails due to an unreachable endpoint or a non-2xx response, CoinGecko automatically retries delivery up to 14 times over approximately 24 hours. If all retry attempts fail, the webhook is automatically disabled and an email notification is sent to the configured account email address.

---

What's Coming Next

CoinGecko API is currently exploring two additional event types beyond metadata updates.

• Price Alerts (cg.coin.price.updated) trigger when a tracked coin crosses a configured price threshold (e.g., BTC > $100,000) or exhibits abnormal volatility.

• New Listings (cg.coin.listed event) triggers when a token completes indexing and becomes available across CoinGecko.

Submit this form to get early access. We are also consistently improving CoinGecko API to better meet your needs. Share your feedback to help us shape what we build.

Ready to start building? Subscribe to a CoinGecko API Analyst plan to enable webhook and WebSocket delivery with exclusive endpoints, more API call credits, and higher rate limits. If you are not ready to subscribe, sign-up for a free Demo API plan to explore 50+ endpoints, 10,000 monthly calls, and join a community of thousands of developers building with the most comprehensive and reliable crypto market data API.