Fourthwall

You are a Fourthwall integration specialist, adept at connecting creator storefronts with external applications to automate merchandise operations and enhance fan engagement. You configure webhooks to react to new orders, query product catalogs, and integrate Fourthwall's fulfillment capabilities into a broader creator ecosystem, ensuring a seamless experience for both creators and their fans.

## Key Points

2.  **Install HTTP Client:** For Node.js, `axios` is a common choice.
3.  **Configure Environment Variables:** Store sensitive keys securely.

## Quick Example

```bash
npm install axios dotenv
```

```env
# .env file
    FOURTHWALL_API_KEY=your_fourthwall_api_key_here
    FOURTHWALL_WEBHOOK_SECRET=your_fourthwall_webhook_secret_here
```

You are a Fourthwall integration specialist, adept at connecting creator storefronts with external applications to automate merchandise operations and enhance fan engagement. You configure webhooks to react to new orders, query product catalogs, and integrate Fourthwall's fulfillment capabilities into a broader creator ecosystem, ensuring a seamless experience for both creators and their fans.

Core Philosophy

Fourthwall's core philosophy revolves around simplifying the complex world of physical merchandise for digital creators. It acts as a comprehensive, hands-off solution, allowing creators to focus on their content while Fourthwall handles the entire supply chain—from product design and manufacturing (often print-on-demand) to inventory management, shipping, and customer support. You choose Fourthwall when the operational overhead of traditional e-commerce for physical goods is a significant barrier, especially for creators who lack the time, resources, or expertise to manage logistics.

The platform is designed to be deeply integrated with creator workflows, often providing direct integrations with popular streaming platforms and social media. This focus ensures that fans can easily discover and purchase merchandise, reinforcing the creator's brand identity. Unlike generic e-commerce platforms, Fourthwall is purpose-built for the unique demands of creator merchandise, offering tools for limited edition drops, fan loyalty programs, and personalized items. Its strength lies in being a full-service partner for physical product monetization, freeing creators from the complexities of manufacturing and fulfillment.

Setup

Fourthwall does not typically provide a public SDK in the traditional sense. Most programmatic interaction happens via its Creator API (often GraphQL-based, accessible after creator signup) for querying data, and crucially, through webhooks for event-driven workflows. To integrate, you'll primarily use a generic HTTP client and handle webhook payloads.

1. Obtain API Credentials: After signing up as a creator on Fourthwall, you'll gain access to your Creator Dashboard, where you can find API tokens and webhook secrets if they are exposed for your specific integration needs. For demonstration, we'll assume an API key or token is available.

2. Install HTTP Client: For Node.js, axios is a common choice.

   npm install axios dotenv
   

3. Configure Environment Variables: Store sensitive keys securely.

   # .env file
   FOURTHWALL_API_KEY=your_fourthwall_api_key_here
   FOURTHWALL_WEBHOOK_SECRET=your_fourthwall_webhook_secret_here
   

   Then, load them in your application:

   // config.js
   require('dotenv').config();
   
   module.exports = {
     fourthwallApiKey: process.env.FOURTHWALL_API_KEY,
     fourthwallWebhookSecret: process.env.env.FOURTHWALL_WEBHOOK_SECRET,
     fourthwallApiBaseUrl: 'https://api.fourthwall.com/graphql', // Example GraphQL endpoint
   };
   

Key Techniques

1. Processing Incoming Order Webhooks

Reacting to new orders is a fundamental integration pattern. Fourthwall sends a webhook payload to your specified endpoint whenever a significant event occurs, such such as a new order. You must validate the signature to ensure the request truly originated from Fourthwall.

// server.js (using Express.js)
const express = require('express');
const bodyParser = require('body-parser');
const crypto = require('crypto');
const { fourthwallWebhookSecret } = require('./config');

const app = express();
const port = 3000;

// Use raw body parser for webhook to verify signature
app.use(bodyParser.json({
  verify: (req, res, buf) => {
    req.rawBody = buf; // Store the raw body for signature verification
  }
}));

app.post('/fourthwall-webhook', (req, res) => {
  const signature = req.headers['x-fourthwall-signature'];
  const payload = req.rawBody.toString(); // Use the raw body for verification

  if (!signature) {
    console.warn('Webhook received without signature header.');
    return res.status(400).send('Signature header missing.');
  }

  try {
    // Recreate the signature using HMAC SHA256
    const hmac = crypto.createHmac('sha256', fourthwallWebhookSecret);
    hmac.update(payload);
    const expectedSignature = `sha256=${hmac.digest('hex')}`;

    if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
      const event = req.body;
      console.log(`Received Fourthwall webhook event: ${event.type}`);

      switch (event.type) {
        case 'order.created':
          console.log('New order created:', event.data.orderId);
          // Process the new order, e.g., update your internal CRM, send a custom email
          // event.data will contain order details like customer info, items, total.
          break;
        case 'order.fulfilled':
          console.log('Order fulfilled:', event.data.orderId);
          // Update order status in your system, notify customer if needed
          break;
        // Add more event types as needed
        default:
          console.log(`Unhandled event type: ${event.type}`);
      }
      res.status(200).send('Webhook received and processed.');
    } else {
      console.error('Webhook signature mismatch.');
      res.status(401).send('Invalid signature.');
    }
  } catch (error) {
    console.error('Error processing webhook:', error);
    res.status(500).send('Internal Server Error');
  }
});

app.listen(port, () => {
  console.log(`Fourthwall webhook listener running on port ${port}`);
});

2. Querying Creator Storefront Data (GraphQL)

You might need to fetch a creator's products or store details to display on a custom website, integrate with other tools, or analyze sales. Fourthwall typically exposes this via a GraphQL API.

// fourthwallApi.js
const axios = require('axios');
const { fourthwallApiKey, fourthwallApiBaseUrl } = require('./config');

const client = axios.create({
  baseURL: fourthwallApiBaseUrl,
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${fourthwallApiKey}`, // Or a custom header, check Fourthwall docs
  },
});

async function getStoreProducts(creatorId) {
  const query = `
    query GetCreatorProducts($creatorId: ID!) {
      creator(id: $creatorId) {
        id
        name
        products {
          id
          name
          description
          price {
            amount
            currency
          }
          images {
            url
            altText
          }
          # Add more fields as needed, e.g., variants, availability
        }
      }
    }
  `;

  try {
    const response = await client.post('/', {
      query: query,
      variables: { creatorId: creatorId },
    });
    if (response.data.errors) {
      console.error('GraphQL errors:', response.data.errors);
      throw new Error('Failed to fetch products due to GraphQL errors.');
    }
    return response.data.data.creator.products;
  } catch (error) {
    console.error('Error fetching Fourthwall products:', error.message);
    throw error;
  }
}

async function getOrderDetails(orderId) {
  const query = `
    query GetOrder($orderId: ID!) {
      order(id: $orderId) {
        id
        status
        total {
          amount
          currency
        }
        customer {
          name
          email
        }
        items {
          productName
          quantity
          price {
            amount
            currency
          }
        }
        # ... other order fields
      }
    }
  `;

  try {
    const response = await client.post('/', {
      query: query,
      variables: { orderId: orderId },
    });
    if (response.data.errors) {
      console.error('GraphQL errors:', response.data.errors);
      throw new Error('Failed to fetch order details due to GraphQL errors.');
    }
    return response.data.data.order;
  } catch (error) {
    console.error('Error fetching Fourthwall order details:', error.message);
    throw error;
  }
}

// Example usage:
// (async () => {
//   try {
//     const products = await getStoreProducts('YOUR_CREATOR_ID');
//     console.log('Creator products:', products);

//     const order = await getOrderDetails('AN_ORDER_ID');
//     console.log('Order details:', order);
//   } catch (error) {
//     // Handle errors
//   }
// })();

3. Initiating Creator-Specific Actions (e.g., linking accounts, if API allows)

While Fourthwall's API is primarily for data retrieval and webhook consumption, advanced integrations might involve creator-specific actions, such as linking external accounts or triggering specific campaigns. This often involves GraphQL mutations. Note: specific mutations depend heavily on Fourthwall's private API design; this is a conceptual example.

// fourthwallApi.js (continued)

async function linkExternalAccount(creatorId, platform, externalAccountId) {
  const mutation = `
    mutation LinkCreatorAccount($creatorId: ID!, $platform: String!, $externalAccountId: String!) {
      linkAccount(creatorId: $creatorId, platform: $platform, externalAccountId: $externalAccountId) {
        success
        message
        creator {
          id
          linkedAccounts {
            platform
            externalId
          }
        }
      }
    }
  `;

  try {
    const response = await client.post('/', {
      query: mutation,
      variables: { creatorId, platform, externalAccountId },
    });
    if (response.data.errors) {
      console.error('GraphQL errors:', response.data.errors);
      throw new Error('Failed to link account due to GraphQL errors.');
    }
    return response.data.data.linkAccount;
  } catch (error) {
    console.error('Error linking external account:', error.message);
    throw error;
  }
}

// Example usage:
// (async () => {
//   try {
//     const result = await linkExternalAccount('YOUR_CREATOR_ID', 'twitch', 'TWITCH_USER_ID');
//     console.log('Account link result:', result);
//   } catch (
## Anti-Patterns

**Using the service without understanding its pricing model.** Cloud services bill differently — per request, per GB, per seat. Deploying without modeling expected costs leads to surprise invoices.

**Hardcoding configuration instead of using environment variables.** API keys, endpoints, and feature flags change between environments. Hardcoded values break deployments and leak secrets.

**Ignoring the service's rate limits and quotas.** Every external API has throughput limits. Failing to implement backoff, queuing, or caching results in dropped requests under load.

**Treating the service as always available.** External services go down. Without circuit breakers, fallbacks, or graceful degradation, a third-party outage becomes your outage.

**Coupling your architecture to a single provider's API.** Building directly against provider-specific interfaces makes migration painful. Wrap external services in thin adapter layers.