Webhooks

Why Use Webhooks?

Getting Started

1

Create a webhook

Go to the Developer Dashboard and create a new webhook endpoint.

2

Get your Signing Secret

Use the Signing Secret to verify incoming payloads on your server.

3

Start receiving events

Your server will receive POST requests whenever relevant coin data changes on CoinGecko.com.

Event Types

HTTP Headers

Signature Verification

Example Code

Replace YOUR_SIGNING_SECRET with the whsec_... value from your Developer Dashboard.

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

const SIGNING_SECRET = 'YOUR_SIGNING_SECRET';

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

  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;
}

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) {
    const event = JSON.parse(rawBodyString);
    // Process the event...
    return res.status(200).send('Webhook received successfully');
  } else {
    return res.status(401).send('Invalid signature');
  }
});

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

import hmac
import hashlib
from flask import Flask, request

app = Flask(__name__)
SIGNING_SECRET = 'YOUR_SIGNING_SECRET'

def verify_signature(body_str, headers, secret):
    if not secret:
        return None

    timestamp = headers.get('x-cg-timestamp')
    event_id = headers.get('x-cg-event-id')
    signature = headers.get('x-cg-signature')

    if not timestamp or not event_id or not signature:
        return None

    signing_string = f"{timestamp}:{event_id}:{body_str}"

    expected = hmac.new(
        secret.encode('utf-8'),
        signing_string.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

@app.route('/webhook', methods=['POST'])
def webhook_handler():
    raw_body_string = request.get_data(as_text=True)
    is_valid = verify_signature(raw_body_string, request.headers, SIGNING_SECRET)

    if is_valid is None:
        return "Missing required CoinGecko headers", 400

    if is_valid:
        event = request.get_json()
        # Process the event...
        return "Webhook received successfully", 200
    else:
        return "Invalid signature", 401

if __name__ == '__main__':
    app.run(port=3000)

Managing Webhooks

• Send Test Event — dispatches a mock cg.coin.info.updated payload. Use it to verify your server receives the request and responds with 2xx before going live.
• Delivery Logs — view the latest 100 delivery attempts. Use these to identify if your endpoint is rejecting requests.

Billing & Credits

• 10 credits per event delivery. Retries are not charged.
• If you run out of credits with Hardcap enabled (Overage disabled):
  • Delivery stops immediately and all webhooks are auto-disabled.
  • You’ll receive an email notification that delivery has stopped.
  • You must manually re-activate webhooks in the Developer Dashboard after credits are replenished.

Estimated Usage

• Expected volume: up to 200 updates/day based on historical data.
• Estimated monthly cost: ~6,000 events/month = ~60,000 credits.
• Plan fit: comfortably within the Analyst plan and above.

24-Hour Baseline Test

1. Enable Hardcap — turn OFF “Overage” in the Developer Dashboard to avoid unexpected charges.
2. Run for 24–48 hours — activate your webhook and let it collect events.
3. Check consumption — review credit usage in the dashboard to establish a reliable baseline.

Retries & Failed Attempts

1. Check your server logs and resolve the issue.
2. Log in to the Developer Dashboard.
3. Manually toggle the webhook back to Active.