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 checkout, NFT minting, and order fulfillment.

Event Types

Checkout webhooks track the full order lifecycle with these 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

Create an Endpoint Route

Using a standard nodejs API server, create an endpoint.

I don't have a webserver or want to test locally

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.

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.

Review Example Webhook Responses

Every Checkout webhook (orders.*) is delivered as { actionId, type, data }:

actionId — the order identifier
type — the event name (for example, orders.delivery.completed)
data — the complete order object, identical to the Get Order API response

The fields inside data.lineItems depend on the order execution mode. exact-out orders (for example, NFT purchases) carry callData (when present) and quantity. exact-in orders (for example, token or memecoin purchases) carry executionParams and maxSlippageBps.

orders.quote.created

{
    "actionId": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
    "type": "orders.quote.created",
    "data": {
        "orderId": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
        "phase": "payment",
        "locale": "en-US",
        "lineItems": [
            {
                "chain": "polygon",
                "executionMode": "exact-out",
                "quantity": 1,
                "callData": { "quantity": 1 },
                "metadata": {
                    "name": "Collection Name",
                    "description": "Collection Description",
                    "imageUrl": "https://..."
                },
                "quote": {
                    "status": "valid",
                    "charges": { "unit": { "amount": "0.50", "currency": "usd" } },
                    "totalPrice": { "amount": "0.50", "currency": "usd" }
                },
                "delivery": {
                    "status": "awaiting-payment",
                    "recipient": {
                        "locator": "email:user@example.com:polygon",
                        "email": "user@example.com",
                        "walletAddress": "0x1234..."
                    }
                }
            }
        ],
        "quote": {
            "status": "valid",
            "quotedAt": "2024-11-20T12:00:00.000Z",
            "expiresAt": "2024-11-20T13:00:00.000Z",
            "totalPrice": { "amount": "0.50", "currency": "usd" }
        },
        "payment": {
            "status": "awaiting-payment",
            "method": "stripe-payment-element",
            "currency": "usd",
            "receiptEmail": "user@example.com"
        }
    }
}

orders.payment.succeeded

{
    "actionId": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
    "type": "orders.payment.succeeded",
    "data": {
        "orderId": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
        "phase": "delivery",
        "locale": "en-US",
        "lineItems": [
            {
                "chain": "polygon",
                "executionMode": "exact-out",
                "quantity": 1,
                "callData": { "quantity": 1 },
                "metadata": { "name": "Collection Name", "imageUrl": "https://..." },
                "quote": {
                    "status": "valid",
                    "totalPrice": { "amount": "0.50", "currency": "usd" }
                },
                "delivery": {
                    "status": "in-progress",
                    "recipient": {
                        "locator": "email:user@example.com:polygon",
                        "email": "user@example.com",
                        "walletAddress": "0x1234..."
                    }
                }
            }
        ],
        "quote": {
            "status": "valid",
            "totalPrice": { "amount": "0.50", "currency": "usd" }
        },
        "payment": {
            "status": "completed",
            "method": "stripe-payment-element",
            "currency": "usd",
            "receiptEmail": "user@example.com",
            "received": { "amount": "0.50", "currency": "usd" }
        }
    }
}

orders.delivery.completed (NFT / exact-out)

{
    "actionId": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
    "type": "orders.delivery.completed",
    "data": {
        "orderId": "7723139d-fba3-474d-8e52-0ac7512d5c7b",
        "phase": "completed",
        "locale": "en-US",
        "lineItems": [
            {
                "chain": "polygon",
                "executionMode": "exact-out",
                "quantity": 1,
                "callData": { "quantity": 1 },
                "metadata": { "name": "Collection Name", "imageUrl": "https://..." },
                "quote": {
                    "status": "valid",
                    "totalPrice": { "amount": "0.50", "currency": "usd" }
                },
                "delivery": {
                    "status": "completed",
                    "recipient": {
                        "locator": "email:user@example.com:polygon",
                        "email": "user@example.com",
                        "walletAddress": "0x1234..."
                    },
                    "txId": "0x2e69f11dae7869b92e3d5eaf4cadd50c48b5c6803d1232815f979d744521ad4c",
                    "tokens": [
                        {
                            "locator": "polygon:0xE04Cf294985282Ddc088E6433c064cfB85eD9EdA:3",
                            "contractAddress": "0xE04Cf294985282Ddc088E6433c064cfB85eD9EdA",
                            "tokenId": "3"
                        }
                    ]
                }
            }
        ],
        "quote": {
            "status": "valid",
            "totalPrice": { "amount": "0.50", "currency": "usd" }
        },
        "payment": {
            "status": "completed",
            "method": "stripe-payment-element",
            "currency": "usd",
            "receiptEmail": "user@example.com",
            "received": { "amount": "0.50", "currency": "usd" }
        }
    }
}

orders.delivery.completed (token / exact-in)

{
    "actionId": "2795199f-f599-44c4-84dc-38d944853a05",
    "type": "orders.delivery.completed",
    "data": {
        "orderId": "2795199f-f599-44c4-84dc-38d944853a05",
        "phase": "completed",
        "locale": "en-US",
        "lineItems": [
            {
                "chain": "base",
                "executionMode": "exact-in",
                "executionParams": {
                    "mode": "exact-in",
                    "amount": "5",
                    "contractAddress": "0x4ed4e862860bed51a9570b96d89af5e1b0efefed",
                    "quantity": 1
                },
                "maxSlippageBps": "50",
                "metadata": {
                    "name": "DEGEN",
                    "description": "DEGEN is a community-driven token..."
                },
                "quote": {
                    "status": "valid",
                    "totalPrice": { "amount": "5", "currency": "usd" }
                },
                "delivery": {
                    "status": "completed",
                    "recipient": {
                        "locator": "base:0x24573a80ae60c0e75735843f119ab4623a45e523",
                        "walletAddress": "0x24573a80ae60c0e75735843f119ab4623a45e523"
                    },
                    "txId": "0x8e20e4b1edff7375fb5d4fc87f6cdb66aa03573e725d5eacc7053800a4f1c11b",
                    "tokens": [
                        {
                            "locator": "base:0x4ed4e862860bed51a9570b96d89af5e1b0efefed:0",
                            "contractAddress": "0x4ed4e862860bed51a9570b96d89af5e1b0efefed",
                            "tokenId": "0",
                            "quantity": "50000000000000000000",
                            "symbol": "DEGEN",
                            "decimals": 18
                        }
                    ]
                }
            }
        ],
        "quote": {
            "status": "valid",
            "totalPrice": { "amount": "5", "currency": "usd" }
        },
        "payment": {
            "status": "completed",
            "method": "basis-theory",
            "currency": "usd",
            "received": { "amount": "5", "currency": "usd" }
        }
    }
}

orders.delivery.failed

{
    "actionId": "2795199f-f599-44c4-84dc-38d944853a05",
    "type": "orders.delivery.failed",
    "data": {
        "orderId": "2795199f-f599-44c4-84dc-38d944853a05",
        "phase": "completed",
        "locale": "en-US",
        "lineItems": [
            {
                "chain": "base",
                "executionMode": "exact-in",
                "executionParams": {
                    "mode": "exact-in",
                    "amount": "5",
                    "contractAddress": "0x4ed4e862860bed51a9570b96d89af5e1b0efefed",
                    "quantity": 1
                },
                "maxSlippageBps": "50",
                "metadata": {
                    "name": "DEGEN",
                    "description": "DEGEN is a community-driven token..."
                },
                "quote": {
                    "status": "valid",
                    "totalPrice": { "amount": "5", "currency": "usd" }
                },
                "delivery": {
                    "status": "failed",
                    "failureReason": {
                        "code": "slippage-tolerance-exceeded"
                    },
                    "recipient": {
                        "locator": "base:0x24573a80ae60c0e75735843f119ab4623a45e523",
                        "walletAddress": "0x24573a80ae60c0e75735843f119ab4623a45e523"
                    }
                }
            }
        ],
        "quote": {
            "status": "valid",
            "totalPrice": { "amount": "5", "currency": "usd" }
        },
        "payment": {
            "status": "completed",
            "method": "basis-theory",
            "currency": "usd",
            "received": { "amount": "5", "currency": "usd" },
            "refunded": { "amount": "5", "currency": "usd" }
        }
    }
}

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

Configure in Crossmint Console

Navigate to the Webhooks page in the console
Click Add Endpoint
Enter your endpoint URL
Select the webhook events to receive
Click Create

Verify Webhook Signatures

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

See the Verify Webhooks guide for implementation details.

Testing Webhooks

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

Watch a video tutorial

Introduction

Quickstarts ⚡

Concepts

Guides

API Reference

Webhooks

Webhooks Overview

Event Types

Setting Up Webhooks

Testing Webhooks