Webhook Configurations

Configure webhook URLs in the Developer Dashboard to have NFTgate call your backend service when notable user events happen. Webhooks are configured for the entire organization and separated by testnet and production checkouts.

Webhook Events

The following webhook events are emitted from our backend.

There currently is not a way to filter which events are sent to your webhook URLs, and NFTgate may add new webhook event types without notice.

Please handle unexpected or unused event types by returning a 2xx response code so our backend does not retry.

Event	Description
payment:succeeded	A buyer successfully paid with a supported payment method.
payment:failed	A buyer paid but their payment method was rejected. Extra data fields may be available with information from our payment processor on failure reason.
payment:refunded	A buyer’s payment is refunded because NFTgate is unable to mint the NFT for some reason. Extra data fields may be available with the reason for the refund.
payment:hold_created	A buyer’s payment method has a pre-authorization hold created for the given amount. They are not charged yet.You can capture or cancel this transaction hold later.
transfer:succeeded	A buyer successfully received their purchase to their wallet.
transfer:failed	A buyer failed to receive their purchase to their wallet. Note: NFTgate’s engineering team is notified when this occurs to debug and attempt to resolve the issue manually (e.g. retry the transaction or refund the buyer).

HTTP Request Format

NFTgate will call your backend with an HTTPS request:

POST 

// headers
Content-Type: application/json
X-NFTgate-Signature: 

// body
{
  "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,
    "networkFeeUsd": 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 NFTgate Checkout",
    "transactionHash": "0x076d1b496152efd2a97d0db1d558c681188a1a76a8a2c271a33e4c34cc1fa467",
    "valueInCurrency": "0.05",
    "currency": "ETH",
    "metadata": {
      "myAppUserId": "23a9fj2930gya0"
    },
    "mintMethod": { ... },
    "eligibilityMethod": { ... },
    "contractArgs": { ... }, 
  }
}

Configuration
Webhooks will retry every 5 minutes for one hour until it receives a 2xx response code (13 attempts total).
Webhooks will originate from the IP address 44.225.232.73.

View Recent Events

View the 20 most recent webhook events emitted along with the request payload, response status code, and response body returned by your backend. This log is useful to debug missing or mishandled webhook handlers.

List webhook events

Test Your Webhook Integration

NFTgate will send a dummy payload to your webhook URL and display the response status and response body.

Test webhook URL

Verify the Signature Header

NFTgate signs each webhook request with a signature in the X-NFTgate-Signature header. This signature ensures you can trust that the request comes from NFTgate.

To verify the signature, create a SHA-256 HMAC hash with the API key as the secret and the body payload as the message (as a JSON-encoded string).

Here’s an example in Node with Typescript (simplified for clarity):

import { createHmac, timingSafeEqual } from 'crypto';

// In your webhook HTTP handler
const signature = req.headers['X-NFTgate-Signature'];
const hash = createHmac('sha256', YOUR_API_KEY)
  .update(JSON.stringify(req.body)) // {"event":"transfer:succeeded","result":{"id":...
  .digest('hex');

if (!timingSafeEqual(Buffer.from(signature), Buffer.from(hash))) {
  // Signature mismatch: Reject this request
} else {
  // Signature match: Continue processing this request
}

Troubleshooting

Here are common issues if you’re not processing webhook calls successfully.

Check if your server framework is reading the header properly. Some frameworks like Next.js lowercase all header names.
Make sure you’re passing the entire body as the message in the HMAC signature. Some frameworks require you to configure the middleware to not parse the request body.
Make sure the API key you’re using matches the one shown in the Developer Dashboard.
Webhook URLs must be https endpoints that are internet accessible. Do not provide a localhost URL to test your local server. Instead use a service like ngrok to make your local server internet accessible.