Minting API Webhooks

Minting NFTs using the minting API is fast -- it normally takes a few seconds -- but can take a bit longer depending on blockchain congestion and other factors.

Sometimes you will want to notify your customers once their NFT is ready. For example you may want to update your app UI to indicate success, or send them an email with instructions to access their NFT.

To do so, we recommend the usage of webhooks. This guide will show you how to configure them and use them to listen for mint completion events on your project.

Creating an endpoint to listen and parse webhook events

For this guide we will use node-js to create an api endpoint to handle webhook events.

1️⃣ Create an endpoint route

Using a standard node api server, create an endpoint.

2️⃣ Configure endpoint to read and parse webhook events

On this endpoint, modify the code to handle POST requests only. When a POST request comes through, parse the webhook event off of the request body. Finally, don't forget to respond with a 200 status code. If you don't, the webhook may keep getting called until you acknowledge it.

The snippet below is an example skeleton that parses webhook events

// endpoint.js

// listen to webhook ingestion 
export default function handler(req, res) {
  if (req.method === "POST") {
    console.log(`[webhook] Successfully minted ${req.body.id}`);
  }
  res.status(200).json({});
}

The mint.succeeded event looks like the following:

{
  type: 'mint.succeeded',
  status: 'success',
  collectionId: <collectionid>,
  id: <crossmint-id>,
  walletAddress: <destination wallet>,
  txId: <transactionId>
}

{
  type: 'mint.succeeded',
  status: 'success',
  collectionId: <collectionid>,
  id: <crossmint-id>,
  walletAddress: <destination wallet>,
  mintHash: <minthash>
}

3️⃣ Pre & post processing

When setting up your webhook listener this is a great time to add your pre and post processing logic. For example, you can call back to your database when a certain id has succeeded or even use Sendgrid or EmailJS to send an email to a recipient when a mint completes. (email template)

Set up

You must now enable webhooks from the Crossmint console

1️⃣ Navigate to the Webhooks tab

Go to the Crossmint console (staging.crossmint.com/console or www.crossmint.com/console). There, navigate to the Webhooks tab on the top right.

2️⃣ Register your endpoint

Once you navigate to Webhooks menu you can click Add an Endpoint.

Use the endpoint URL determined at the start of this guide and select the mint.succeeded scope. Click Save Webhook and you are done!

Once done, you'll be redirected to a modal that shows your webhook and any triggered events.

Now the last thing left to do is to test the endpoint. To do so, mint one or two NFTs with the API and see the responses come through.

🚧

Don't have a webserver or want to test locally?

No problem! You can test locally by installing ngrok and creating a routed endpoint to a specified port.

Webhook video walkthrough