Webhooks

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.

Name	Key	Description
Order listed	ORDER_LISTED	A new order was created. Works on both on-chain and off-chain orders.
Order cancelled	ORDER_CANCELLED	An order was cancelled. Any cancellation reason is possible.
Order filled	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';

const SIGNATURE_ALGORITHM = 'RSA-SHA256'
const SIGNATURE_OUTPUT_FORMAT = 'base64'
const PRIVATE_KEY_ENCODING = 'utf8'

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)
  verifier.end()

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