​

Webhooks Overview

Webhooks allow you to track the status of payments and order lifecycle events in your application. They provide real-time notifications for various events like payment processing, NFT minting, and order fulfillment.

​

Webhook Systems by Checkout Version

Crossmint offers different webhook systems for Checkout V2 and V3:

​

Checkout V2 Webhooks (Legacy)

The Checkout V2 webhook system provides basic payment tracking with a single event type:

• purchase.succeeded - Triggered when an NFT has been successfully purchased and delivered

​

Checkout V3 Webhooks (Current)

The Checkout V3 webhook system offers comprehensive order lifecycle tracking with multiple event types:

Quote Phase

• orders.quote.created - Triggered when a new order is created
• orders.quote.updated - Triggered when order details are modified

Payment Phase

• orders.payment.succeeded - Triggered when payment is successfully processed
• orders.payment.failed - Triggered when payment fails

Delivery Phase

• orders.delivery.initiated - Triggered when delivery begins
• orders.delivery.completed - Triggered when delivery succeeds
• orders.delivery.failed - Triggered when delivery fails

​

Setting Up Webhooks

​

1. Create an endpoint route

Using a standard nodejs API server, create an endpoint.

​

2. Configure the endpoint

Your endpoint should:

• Handle POST requests only
• Parse webhook events from the request body
• Respond with a 200 status code to acknowledge receipt

Example handler:

// endpoint.js

export default function handler(req, res) {
    if (req.method === "POST") {
        console.log(`[webhook] Event received:`, req.body);
    }
    res.status(200).json({});
}

​

3. Example Webhook Responses

{
    "type": "orders.quote.created",
    "payload": {
        "totalPrice": {
            "amount": "0.50",
            "currency": "usd"
        },
        "lineItems": [
            {
                "metadata": {
                    "title": "Collection Name",
                    "description": "Collection Description",
                    "imageUrl": "https://..."
                },
                "price": {
                    "amount": "0.50",
                    "currency": "usd"
                },
                "quantity": 1
            }
        ]
    }
}

{
    "type": "orders.payment.succeeded",
    "payload": {
        "orderIdentifier": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
        "paymentMethodType": "credit-card",
        "totalPrice": {
            "amount": "0.50",
            "currency": "usd"
        }
    }
}

{
    "type": "orders.delivery.completed",
    "payload": {
        "orderIdentifier": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
        "txId": "0x2e69f11dae7869b92e3d5eaf4cadd50c48b5c6803d1232815f979d744521ad4c",
        "contractAddress": "0xE04Cf294985282Ddc088E6433c064cfB85eD9EdA",
        "tokenIds": ["3"],
        "recipient": {
            "walletAddress": "0x..."
        }
    }
}

​

4. Pass Custom Arguments (Optional)

You can pass custom arguments through webhooks to track additional information:

• User IDs (If you want additional security, sign this ID with a custom key, or send it as a signed JWT, and verify its integrity later on your server)
• Timestamps
• Product SKUs
• Custom metadata

Example of passing arguments:

function NFTSalePage() {
    const whArgs = {
        uid: 123424,
        sku: 123123123,
        metadata: { custom: "data" },
    };

    const whArgsSerialized = JSON.stringify(whArgs);

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

Then, extract them on the server:

export default function handler(req, res) {
    const { whPassThroughArgs } = req.body;

    if (whPassThroughArgs) {
        const whArgsDeserialized = JSON.parse(whPassThroughArgs);
        console.log(whArgsDeserialized);
    }

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

​

5. 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.

​

6. Configure in Crossmint Console

1. Navigate to the Webhooks page in the console
2. Click Add Endpoint
3. Enter your endpoint URL
4. Select the webhook events to receive
5. Click Create

​

6. Security

For security, verify webhook signatures using the signing secret from your endpoint details page:

See the Verify Webhooks guide for implementation details.

​

Testing Webhooks

1. Use test card number 4242 4242 4242 4242 for successful payments
2. Use 4000 0000 0000 4954 to test payment failures
3. Monitor webhook deliveries in the Console