Webhooks settings

Webhooks can be set up on the endpoint of your choice so that you will receive events related to order modifications. You can define what events you want to subscribe to and at what URL for each collection in your dashboard. If you prefer, you can also use webhooks admin routes.

Webhooks event list

Webhook events cover the different states of the Order flow.


Order listed


A new order was created. Works on both on-chain and off-chain orders.

Order cancelled


An order was cancelled. Any cancellation reason is possible.

Order filled


An order was filled entirely.

Webhook event data

The webhook event data you will receive always follows the same schema regardless of the event type. You can find an example in the callback payload sample of the webhook subscription route or a more precise schema in the SDK corresponding type. If your backend is written in typescript we advise to reuse this SDK type.

Validating the origin of webhooks

Since your webhook route will be public, you must validate that the webhooks you receive come from our system, not from a malicious party. The validation method we use is based on an RSA private/public key pair. The webhook public key is available in its dedicated route.

The webhook signature is included in the header x-cometh-indexer-signature of the request.

Validating the webhook in node.js, using the native crypto library, would look like this:

import { createVerify } from 'crypto';


export const validateWebhookEvent = async (
  webhookEvent: WebhookEvent,
  signature: string
): Promise<boolean> => {
  // Step 1: Retrieve the public key
  const webhookPublicKey = await marketplaceSdk.webhook.getWebhookPublicKey()
  // Step 2: Create a verifier
  const verifier = createVerify(SIGNATURE_ALGORITHM)
  verifier.update(JSON.stringify(webhookEvent), PRIVATE_KEY_ENCODING)

  // Step 3: Verify the signature
  return verifier.verify(webhookPublicKey, signature, SIGNATURE_OUTPUT_FORMAT)

Last updated