Crossmint
Search…
Crossmint Webhooks
Questions? Contact us at www.crossmint.io/support
Your user just purchased an NFT using Crossmint. Now what? You may want to...
  • Store a receipt of it in your database
  • Associate a user wallet account with their account in your system
  • Show some celebratory confetti UI 🎊
  • ...
You can do this all using webhooks!

How it works

  1. 1.
    When you create a project on Crossmint, you can associate an endpoint in your server to receive webhook events.
  2. 2.
    When a user purchases an NFT using Crossmint, you receive an HTTPS request at your webhook URL. This request contains the user's wallet, the NFT address, as well as custom parameters you are able to pass on the client side using the Crossmint Client SDK.
  3. 3.
    Your webhook will receive a JSON object containing status, walletAddress, and optional passThroughArgs (see below).
  4. 4.
    If your project is on Solana you will also receive a mintAddress value corresponding to the mint hash of the NFT.
  5. 5.
    If your project is EVM (ethereum, polygon, avalanche) you will receive contractAddress and tokenId attributes in the JSON payload.
NOTE: if someone minted multiple tokens at once on an EVM chain, we currently only fire a webhook with the first token ID.

Integrate

Step 1: Register your webhook endpoint

First, navigate to www.crossmint.io/console/webhooks and click on "Add Endpoint"
Next, fill in your webhook details:
Enter in the URL where you'd like to receive the webhook, and the events for which you'd like to receive updates, and that's it! When an event occurs, you'll receive a POST request to the designated URL.

Step 2: Handle webhook events

Whenever a customer purchases an NFT using Crossmint, Crossmint will make an HTTPS request to the webhook URL you have configured. Example JSON for each request is below:
purchase.succeeded
export.succeeded
{
"type": "purchase.succeeded",
"status": "success",
"walletAddress": "0x121FA6D986a3d221a0800dE321980fc2fc9c4AB0",
"clientId": "aa4f6c8d-aee4-4cb9-a595-bd6dd422e",
"txId": "0x010a822c8594793e29347d83eb39aac1bf27280fdf08fe443d6f9f48ddd9022a",
"contractAddress": "0x6d23e8cf17c0d3A4Fc5D91e6622c55e9d468d934",
"tokenId": 502,
}
{
"type": "export.succeeded",
"status": "success",
"fromAddress": "F1aCoig7WydcfHWRt8HbvCikcG1RDyfcpZtANdg9yzWY",
"toAddress": "7QuHcRT83gyB4pnMoGrAENKAdsbXbSSL2e6fnc6c6Tga",
"mintAddress": "Hj2cDgLVpUx4YDj8PkxEjs4oQQ92ac28iQQ1q7z59FQ1",
"txId": "42TgxTYtA31G4c9hfwrH2S1gcDCHwKCasieHP46fcd9pBZjRaAZbgiXyP1GZLA9LaRzHe38737mkSq4saB4wMMHy",
}
Your server must return a 2xx HTTP status quickly such that the webhook is marked as delivered successfully.

Step 3: (Optional) Set custom pass-through arguments

When a user initiates the Crossmint flow, you can optionally set some custom arguments that will get passed through to your server webhook at the time of purchase.
Some useful information that you could pass here is:
  • 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.
  • The time of purchase
  • A product SKU
You can pass multiple arguments by serializing them into a single string
​
Pass the arguments (client-side)
function NFTSalePage() {
​
const whArgs = {
uid: 123424,
sku: 123123123,
monkey: true
};
const whArgsSerialized = JSON.stringify(whArgs);
​
return (
...
<CrossmintPayButton
clientId="<YOUR_CLIENT_ID>"
whPassThroughArgs={whArgsSerialized}
/>
);
}
Extract the arguments (server-side)
// 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({});
}
​

Webhook Events

post
https://your.webhook
Mint Succeeded
post
https://your.webhook
Transfer Succeeded
​
Copy link
Outline
How it works
Integrate
Webhook Events
post
Mint Succeeded
post
Transfer Succeeded