Webhooks

A webhook is a way for one application to deliver data to another application in real-time when a specific event occurs. Webhooks are typically used to notify external systems of events in real-time, allowing them to react immediately. This is particularly useful for integrating different services or automating workflows.

​

Quickstart

You will need a Notification URL to create a Webhook. If you don’t already have a URL, you can follow these instructions to set up a Webhook App for receiving notification events. Once configured, you can use the URL to create a webhook and playaround it.

Here’s a quickstart example that does the transfer and receive events for the transfer.

​

Configurations

You can configure webhooks using either the CDP Portal or the CDP SDK.

Note that the maximum number of webhooks you can have is 100 per organization.

​

CDP Portal

The CDP Portal provides a user-friendly interface for setting up and managing your webhooks. Here, you can specify the event types you’re interested in, the endpoint URL where you want to receive the data, and any custom headers or security settings required.

​

CDP SDK

The CDP SDK allows for programmatic configuration of webhooks. It offers a flexible API for subscribing to event types, managing webhook endpoints, and handling security concerns. This is particularly useful for developers looking to integrate webhooks directly into their applications.

​

Event Types and Networks

You can find the list of event types and networks supported here.

​

Security Tips

For all webhook events, the payload includes a webhookId, which identifies the specific webhook that triggered the event. In addition, when POST-ing data to the callback URL, Coinbase will include a header entry in the HTTP request. Its key is “x-coinbase-signature” and its value is generated by concatenating the webhookID and the request body, as an byte array, then hashed using the HMAC-SHA256 algorithm. Client side can generate a corresponding hash and compare it with the signature provided in the request header to ensure that the request indeed originated from Coinbase.

To locate your webhook UUID, navigate to the portal and view the webhook configuration details.

Here are some code examples on how to verify the HMAC signature when receiving a webhook update.

    import crypto from 'crypto';

function hmacVerification(payload, receivedSignature) {
// Webhook ID is the secret key
const webhookId = "6786f1e1c40ad2627a6d4add";

// Generate HMAC signature
const hmac = crypto.createHmac('sha256', webhookId);
hmac.update(payload);
const calculatedSignature = hmac.digest('hex');

// Print results
console.log('calculated:', calculatedSignature);
console.log('expected  :', receivedSignature);
const matched = crypto.timingSafeEqual(
    Buffer.from(calculatedSignature, "hex"),
    Buffer.from(receivedSignature, "hex"),
);
console.log('matched   :', matched);
}

// Example usage
const payload = '{"blockNumber":"20558228","blockTime":"1736896472","eventType":"transaction"}';
const signature = '579b29ff401a75a931f213f634fba2996724e5346b0ddb1356619e35c6fb6e10';
hmacVerification(payload, signature);

​

Retry Policy

When making callbacks, if the HTTP call does not return with a 200 success code, Coinbase will retry the callback up to 5 times with an exponential backoff strategy. After 5 retries, the webhook will be deactivated and you will need to re-activate it manually.