Webhooks

Documentation Index

Fetch the complete documentation index at: https://docs.coingecko.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Why Use Webhooks?

​

Potential Use Cases

​

1. Getting Started

1

Setup Your Webhook

Create a webhook via Developer Dashboard UI.

2

Obtain your Signing Secret key to configure your Webhook server.

3

Done!

You will now receive notification events to your server, whenever there’s a relevant info update for coins listed on CoinGecko.com . Refer to sections below for payload example and more details.

​

2. Event Types

​

3. HTTP Headers

• POST /your-endpoint-url
• Host: your-server.com
• Content-Type: application/json
• x-cg-timestamp: 1776066... (UNIX timestamp of when the event occurred. Useful for replay attack prevention)
• x-cg-signature: 7e7f6... (Cryptographic signature to verify the payload is genuinely from CoinGecko)
• x-cg-event-id: 123... (Unique identifier for the webhook event)

​

4. Security & Signature Verification

​

The Signing Secret

• Location: You can view, reveal, and copy your Signing Secret on the Webhook Details page in your dashboard.
• Important: Treat this signing secret like a password. Do not share it, commit it to public repositories, or expose it in client-side code. It must be kept securely on your backend server.

​

Verifying the Payload (Code Examples)

const { createHmac } = require('crypto');
const express = require('express');
const app = express();

const SIGNING_SECRET = 'whsec_your_signing_secret_here';

function verifySignature(body, headers, secret) {
  if (!secret) return null;

  // STRICTLY use CoinGecko specific headers
  const timestamp = headers["x-cg-timestamp"];
  const eventId = headers["x-cg-event-id"];
  const signature = headers["x-cg-signature"];

  if (!timestamp || !eventId || !signature) return null;

  const signingString = `${timestamp}:${eventId}:${body}`;
  const expected = createHmac("sha256", secret).update(signingString).digest("hex");

  return expected === signature;
}

// Express Route Example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBodyString = req.body.toString('utf8'); 
  const isValid = verifySignature(rawBodyString, req.headers, SIGNING_SECRET);

  if (isValid === null) {
    return res.status(400).send('Missing required CoinGecko headers');
  }

  if (isValid) {
    console.log('✅ Webhook signature verified!');
    const event = JSON.parse(rawBodyString); 
    // Process the event...
    return res.status(200).send('Webhook received successfully');
  } else {
    console.error('❌ Webhook signature mismatch.');
    return res.status(401).send('Invalid signature');
  }
});

app.listen(3000, () => console.log('Server listening on port 3000'));

​

5. Managing and Debugging Webhooks

​

Send Test Event

​

Delivery Logs

​

6. Billing and Credits

• Charge: Credits are deducted for each payload we deliver based on your plan’s credit charge per event (default is 10 credits per event). You are not charged API credits for retry attempts.
• Hardcapping (Overage Disabled): If you run out of credits and have “Overage” disabled (Hardcap enabled) in your Developer Dashboard:
  • We will immediately stop delivering webhook events.
  • All active Webhooks will be auto-disabled.
  • You will receive an email notification indicating that delivery has stopped.
  • Note: When credits are replenished (or overage is re-enabled), you must manually re-activate your webhooks in the Developer Dashboard. We do not automatically turn them back on.

​

Estimating Your Webhook Costs

• Expected Volume: Based on historical data, our data averages up to 200 updates per day.
• Estimated Monthly Cost: This translates up to 6,000 events per month, consuming approximately 60,000 API credits.
• Plan Recommendation: This estimated volume fits comfortably within the monthly credit allowance of the Analyst Plan and higher tiers.

​

Best Practice: The 24-Hour Baseline Test

1. Enable Hardcap: Ensure your “Overage” setting is turned OFF in your Developer Dashboard. This guarantees you will not be charged unexpected overage fees if the volume spikes.
2. Run for 24-48 Hours: Activate your webhook and let it run for a full day or two.
3. Check Your Logs: Review your credit consumption in the dashboard to establish a reliable baseline based on current market conditions.

​

7. Retries and Failed Attempts

​

Retry Mechanism

1. Single Event Backoff: If a specific event delivery fails, we will retry up to 14 times across approximately 24 hours. If the 14th retry fails, we will completely disable the specific Webhook. You will receive an email notification that the webhook endpoint has been disabled.
2. Webhook Disablement (Hard Cap): If your endpoint is continuously unresponsive and experiences 300 failed retries across 12 hours, we will completely disable the specific Webhook. You will receive an email notification that the webhook endpoint has been disabled.