Webhooks

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({});
}

Here are some example responses:

{
    "type": "purchase.succeeded",
    "status": "success",
    "walletAddress": "<EVM_ADDRESS>",
    "projectId": "<PROJECT_ID>",
    "collectionId": "<COLLECTION_ID>",
    "clientId": "<CLIENT_ID>",
    "txId": "<TX_ID>",
    "contractAddress": "<CONTRACT_ADDRESS>",
    "tokenIds": [<TOKEN_IDS>], // only present for EVM collections (eth/polygon)
    "passThroughArgs": "<YOUR_ARGS_JSON>" // only present if you set whPassThroughArgs
}

​

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.

function NFTSalePage() {
    const whArgs = {
        uid: 123424,
        sku: 123123123,
        monkey: true
    };

    const whArgsSerialized = JSON.stringify(whArgs);

    return (
        ...
        <CrossmintPayButton
        projectId="_YOUR_PROJECT_ID_"
        collectionId="_YOUR_COLLECTION_ID_"
        whPassThroughArgs={whArgsSerialized}
        />
    );
}

// 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({});
}

​

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.

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