Skip to main content

​
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.
You can test locally by installing ngrok and creating a routed endpoint to a specified port. > Note: Use ngrok only for testing. In production, ensure your endpoint is properly secured with HTTPS and appropriate access controls.

​
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
Your server must return a 2xx HTTP status quickly so the webhook is marked as delivered.
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({});
}
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.

​
3. Example Webhook 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
    "passThroughArgs": "<YOUR_ARGS_JSON>" // only if whPassThroughArgs set
}

{
    "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)

Custom arguments (whPassThroughArgs) are only supported in Checkout V2 webhooks. This feature is not available in Checkout V3 webhooks (orders.*).
You can pass custom arguments through Checkout V2 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
Add webhook endpoint UI

​
6. Security

For security, verify webhook signatures using the signing secret from your endpoint details page:
Screenshot of webhooks status UI
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