Your user just purchased an NFT using Crossmint. Now what? You may want to...

  • Store a receipt of it in your database
  • Associate a user wallet account with their account in your system
  • Show some celebratory confetti UI 🎊

You can do this easily with webhooks.

How it works

  1. When you register your NFT collection for Crossmint, you can associate an endpoint in your server to receive webhooks.
  2. When a user purchases an NFT using Crossmint, you receive an HTTPs request at your webhook URL. This request contains the user's wallet, the NFT address, as well as custom parameters you are able to pass on the client side using the Crossmint Client SDK.
  3. Your webhook will receive a JSON object containing status, walletAddress, and optional passThroughArgs (see below).
  4. If your project is on Solana you will also receive a mintAddress value corresponding to the hash of the NFT.
  5. If your project is EVM (ethereum, polygon) you will receive contractAddress and tokenId attributes in the JSON payload.

🚧

Caution:

If someone mints multiple tokens at once on an EVM chain, we currently only fire a webhook with the first token ID.

Integrate

Step 1: Register your webhook endpoint

First, navigate to www.crossmint.io/console/webhooks and click on "Add Endpoint"

32483248

Next, fill in your webhook details:

32483248

Enter in the URL where you'd like to receive the webhook, and the events for which you'd like to receive updates, and that's it! When an event occurs, you'll receive a POST request to the designated URL.

Step 2: Listen to webhook events

Whenever a customer purchases an NFT using Crossmint, Crossmint will make an HTTPS request to the webhook URL you have configured. Example JSON for each request is below:

{
    "type": "purchase.succeeded",
    "status": "success",
    "walletAddress": "<EVM_ADDRESS>",
    "clientId": "<CLIENT_ID>",
    "txId": "<TX_ID>",
    "contractAddress": "<CONTRACT_ADDRESS>",
    "tokenId": <TOKEN_ID>, // only present for EVM collections (eth/polygon)
    "passThroughArgs": "<YOUR_ARGS_JSON>" // only present if you set whPassThroughArgs
}
{
    "type": "purchase.succeeded",
    "status": "success",
    "walletAddress": "<SOL_ADDRESS>",
    "clientId": "<CLIENT_ID>",
    "txId": "<TXID>",
    "mintAddress": "<MINT_HASH>",
    "passThroughArgs": "<YOUR_ARGS_JSON>"
}
{
    "type": "export.succeeded",
    "status": "success",
    "fromAddress": "<FROM_ADDRESS>", // crossmint custodial wallet
    "toAddress": "<TO_ADDRESS>",         // user external wallet
    "mintAddress": "<CONTRACT_OR_MINT_HASH>", // evm nft contract / solana mintHash
    "txId": "<TX_ID>"
}

Your server must return a 2xx HTTP status quickly such that the webhook is marked as delivered successfully.

Step 3: (Optional) Set custom pass-through arguments

When a user initiates the Crossmint flow, you can optionally set some custom arguments that will get passed through to your server webhook at the time of purchase.

Some useful information that you could pass here includes:

  • The user's id in your system. For additional security, sign this ID with a custom key, or send it as a signed JWT, and verify its integrity later on your server.
  • The time of purchase
  • A product SKU

You can pass multiple arguments by serializing them into a single string.

Example of handling the pass-through arguments

You can pass the arguments on the client-side:

function NFTSalePage() {

  const whArgs = {
    uid: 123424,
    sku: 123123123,
    monkey: true
  };
  
  const whArgsSerialized = JSON.stringify(whArgs);

  return (
    ...
    <CrossmintPayButton
      clientId="<YOUR_CLIENT_ID>"
      whPassThroughArgs={whArgsSerialized}
    />
  );
}

Then, extract the arguments on the server-side:

// NextJS
export default function handler(req, res) {
  ...
  
  const { whPassThroughArgs } = req.body;
  
  if (whPassThroughArgs) {
    const whArgsDeserialized = JSON.parse(whPassThroughArgs);
    console.log(whArgsDeserialized);
  }

  res.status(200).json({});
}