crossmint-webhooks

Crossmint Webhooks

Crossmint is a wallets, checkout, NFT-minting, verifiable-credential and stablecoin offramp platform. One project-level webhook system carries events from every product: you add an endpoint in the Crossmint console and receive signed JSON POSTs. Deliveries are sent through Svix, so they carry svix-id, svix-timestamp and svix-signature headers and the endpoint's signing secret starts with whsec_.

When to Use This Skill

• How do I receive Crossmint webhooks?
• How do I verify a Crossmint webhook signature (svix-signature)?
• Where do I find my Crossmint webhook signing secret (whsec_...)?
• How do I handle wallets.transfer.in, orders.delivery.completed or nfts.create.succeeded events?
• Why do Crossmint webhook bodies have different shapes (id vs actionId)?
• Why is my Crossmint webhook verification failing?

Verification (core)

Signed content is {svix-id}.{svix-timestamp}.{raw body}, HMAC-SHA256, base64 output. The key is the base64-decoded part of the whsec_... secret after the prefix. Compare against every v1, entry; ignore other versions. If svix-id is absent, read webhook-id, webhook-timestamp and webhook-signature instead, as Hookdeck does. The examples use the svix library (npm and PyPI):

import { Webhook } from 'svix';

// rawBody: exact request body (Buffer or string), NOT re-serialised JSON
function verifyCrossmint(rawBody, headers, secret = process.env.CROSSMINT_WEBHOOK_SECRET) {
  const p = headers['svix-id'] ? 'svix' : 'webhook'; // fall back to the Standard Webhooks names
  const [id, timestamp, signature] = ['id', 'timestamp', 'signature'].map((k) => headers[`${p}-${k}`]);
  new Webhook(secret).verify(rawBody, {
    'svix-id': id, 'svix-timestamp': timestamp, 'svix-signature': signature,
    'webhook-id': id, 'webhook-timestamp': timestamp, 'webhook-signature': signature,
  }); // throws on a bad signature or stale timestamp → respond 400
}