Webhooks

Configure webhook URLs to have thirdweb notify your backend when successful or failed events occur.

• Update your database when a buyer purchases an NFT.
• Send an email to a buyer after their purchase succeeds.
• Inform your team in Slack/Discord when a payment or purchase failed.

The following webhook events are supported.

thirdweb will call your backend with an HTTPS POST request:

Content-Type: application/json
x-thirdweb-signature: <SIGNATURE_FROM_THIRDWEB>

{
  "event": "transfer:succeeded",
  "result": {
    "id": "5bbbada7-e864-4dac-ae4b-0ee4967f55d8",
    "checkoutId": "70e08b7f-c528-46af-8b17-76b0e0ade641",
    "walletAddress": "0x2086Fcd5b0B8F4aFAc376873E861DE00c67D7B83",
    "walletType": "Preset",
    "email": "[email protected]",
    "quantity": 1,
    "paymentMethod": "BUY_WITH_CARD",
    "networkFeeUsd": 0.02,
    "serviceFeeUsd": 1.79,
    "totalPriceUsd": 45.99,
    "createdAt": "2022-08-22T19:15:09.755375+00:00",
    "paymentCompletedAt": "2022-08-22T19:16:01.673+00:00",
    "transferCompletedAt": "2022-08-22T19:16:18.024+00:00",
    "claimedTokens": {
      "collectionAddress": "0x965550329b91b7c703a527347b613E175f38872d",
      "collectionTitle": "My First NFT",
      "tokens": [
        {
          "transferHash": "0x076d1b496152efd2a97d0db1d558c681188a1a76a8a2c271a33e4c34cc1fa467",
          "transferExplorerUrl": "https://polygonscan.com/tx/0x076d1b496152efd2a97d0db1d558c681188a1a76a8a2c271a33e4c34cc1fa467",
          "tokenId": "262",
          "quantity": 1
        }
      ]
    },
    "title": "My First Checkout",
    "transactionHash": "0x076d1b496152efd2a97d0db1d558c681188a1a76a8a2c271a33e4c34cc1fa467",
    "valueInCurrency": "0.05",
    "currency": "ETH",
    "metadata": {
      "myAppUserId": "23a9fj2930gya0"
    },
    "mintMethod": { ... },
    "eligibilityMethod": { ... },
    "contractArgs": { ... },
  }
}

{
  "event": "transfer:succeeded",
  "result": {
    "id": "5bbbada7-e864-4dac-ae4b-0ee4967f55d8",
    "checkoutId": "70e08b7f-c528-46af-8b17-76b0e0ade641",
    "walletAddress": "0x2086Fcd5b0B8F4aFAc376873E861DE00c67D7B83",
    "walletType": "Preset",
    "email": "[email protected]",
    "quantity": 1,
    "paymentMethod": "BUY_WITH_CARD",
    "networkFeeUsd": 0.02,
    "serviceFeeUsd": 1.79,
    "totalPriceUsd": 45.99,
    "createdAt": "2022-08-22T19:15:09.755375+00:00",
    "paymentCompletedAt": "2022-08-22T19:16:01.673+00:00",
    "transferCompletedAt": "2022-08-22T19:16:18.024+00:00",
    "claimedTokens": {
      "tokens": [
        {
          "transferHash": "0x076d1b496152efd2a97d0db1d558c681188a1a76a8a2c271a33e4c34cc1fa467",
          "transferExplorerUrl": "https://polygonscan.com/tx/0x076d1b496152efd2a97d0db1d558c681188a1a76a8a2c271a33e4c34cc1fa467",
          "tokenId": "262",
          "quantity": 1,
          "from": "0xce6913CA121276E550b82844A08aCB4dfDc09178",
          "collectionAddress": "0x965550329b91b7c703a527347b613E175f38872d",
          "collectionTitle": "My First NFT"
        }
      ]
    },
    "title": "My First Checkout",
    "transactionHash": "0x076d1b496152efd2a97d0db1d558c681188a1a76a8a2c271a33e4c34cc1fa467",
    "valueInCurrency": "0.05",
    "currency": "ETH",
    "metadata": {
      "myAppUserId": "23a9fj2930gya0"
    },
    "mintMethod": { ... },
    "eligibilityMethod": { ... },
    "contractArgs": { ... },
  }
}

Webhooks are configured separately for testnet and production checkout on the dashboard. Webhook URLs must be publicly accessible https endpoints.

Do not provide a localhost URL to test your local server. We recommend testing your development server with a service like ngrok to serve a temporary public URL.

Please return a 2xx response for unexpected or unused event types to prevent unnecessary retries.

To ensure the request came from thirdweb, each webhook request signs the payload and provides this signature in the x-thirdweb-signature header.

To verify this signature, create a SHA-256 HMAC hash with your thirdweb payments secret key that can be found in the thirdweb dashboard payments settings and the body payload as the message (as a JSON-encoded string).

Here's a simplified HTTP handler in Next.js:

import { createHmac, timingSafeEqual } from "crypto";
 
const thirdwebCheckoutsWebhookHandler = (req, res) => {
  const apiKey = "<YOUR_API_KEY>"; // Your thirdweb payments secret key
 
  // Get the provided signature.
  const signature = req.headers["x-thirdweb-signature"];
  // Compute the expected signature.
  const hash = createHmac("sha256", apiKey)
    .update(JSON.stringify(req.body)) // {"event":"transfer:succeeded","result":{"id":...
    .digest("hex");
  // Confirm the provided signature matches.
  if (!timingSafeEqual(Buffer.from(signature), Buffer.from(hash))) {
    return res.status(400).send("Signature mismatch!");
  }
 
  switch (req.body.event) {
    case "transfer:succeeded":
    // Handle when an NFT was delivered.
    case "transfer:failed":
    // Handle when an NFT could not be delivered.
    default:
    // Ignore all other events and return 2xx.
  }
 
  return res.status(200).send("OK");
};

Use the Test webhook button to send a dummy payload to your webhook URL and see response status/body.

Select the List events button to view the recent webhook events, including the request body and response status/body from your backend. This view is useful to debug misconfigured webhook handlers.

If your server is public, a bad actor can spoof a webhook request. Verifying the signature ensures the payload has not been changed. If a bad actor changes the webhook request body, the signature would not match the signed payload.

Here are common reasons the signature header may be mismatched.

• Check if the header is set lower-cased. Some server frameworks (e.g. Next.js) use lowercase request header names since they are case-insensitive (RFC 2616).
• Make sure you're passing the entire body as the message in the HMAC signature. Some frameworks require you to configure the HTTP handler to not parse the request body (e.g. Next.js).
• Make sure your API key is valid.

Webhooks will be sent from the IP address 44.225.232.73.

Webhooks are retried every five minutes for up to one hour until a 2xx response is returned.

Currently there is no way to filter which events are sent to your webhook URLs. thirdweb may add new webhook event types without notice. Please ignore events that you don't need by returning a 2xx response.