Webhooks allow you to track the status of payments. The embedded checkout also offers events as another way to track updates, and the Pay Button allows redirects post-checkout.

Webhooks can also be used to pass custom arguments through the checkout. For example, to track user IDs or measure ad effectiveness.

How to Set up Webhooks

In this guide, we will use nodejs to create an API endpoint to listen for and parse webhook events. To get started:

1. Create an endpoint route

Using a standard nodejs API server, create an endpoint.

2. Configure the 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 of the request body. Ensure your webhook listener responds with a 200 status code. Otherwise the webhook may be sent until you acknowledge it.

The snippet below is an example handler 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({});
}

Don’t be strict with payload validations as Crossmint may add new fields to the webhooks as products evolve.

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

Here are some example responses:

3. (Optional) Pass custom arguments through the webhook

You can pass custom arguments to the SDK and receive them on the webhook responses.

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.
  • A timestamp.
  • A product SKU.

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

4. Pre & post processing

Add your pre and post processing logic when setting up your webhook listener. 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.

5. Setting up webhooks on the Crossmint console

From the console, navigate to the Webhooks tab, and Add an Endpoint with the webhooks you need.

Screenshot of webhooks UI

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

Now the last thing left to do is testing the endpoint. To do so, purchase some NFTs and see the responses come through.

Webhooks Available

Typedescription
purchase.succeededTriggered when an NFT has been successfully purchased. This means the payment was succesfully captured, and the user received the NFT.

Purchases of multiple NFTs on EVM chains will only trigger purchase.succeeded once, with the token ID of the first NFT.