Webhook User Guide

{
 "identifier": "jane.doe@example.com",
 "source": "snowflake",
 "purpose": "Marketing",
 "enabled": true,
 "preferences": [
   { "topic": "ContactMethod", "value": ["Email"] }
 ]
}// code here

export default async function customFunction({ environment, payload, sdk }) {
  const apiKey = environment.TRANSCEND_API_KEY;
  const partition = environment.TRANSCEND_PARTITION;
  const identifierName = environment.IDENTIFIER_NAME || 'email';
  const defaultPurpose = environment.DEFAULT_PURPOSE || 'Marketing';

  if (!apiKey) {
    throw new Error('Missing environment.TRANSCEND_API_KEY');
  }

  if (!partition) {
    throw new Error('Missing environment.TRANSCEND_PARTITION');
  }

  const identifier = resolveIdentifier(payload);
  if (!identifier) {
    throw new Error('Could not resolve user identifier from payload');
  }

  const records = buildPreferenceRecords({
    payload,
    identifier,
    identifierName,
    partition,
    defaultPurpose,
  });

  if (records.length === 0) {
    throw new Error('No preference updates were produced from payload');
  }

  const response = await sdk.fetch('/v1/preferences', {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      records,
      skipWorkflowTriggers: false,
    }),
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(
      `Failed to upsert preferences: ${response.status} ${response.statusText} - ${body}`,
    );
  }
}

function resolveIdentifier(payload) {
  return (
    payload?.user?.email ||
    payload?.user?.id ||
    payload?.identifier ||
    payload?.coreIdentifier?.value ||
    payload?.requestIdentifier?.value ||
    payload?.extras?.profile?.identifier ||
    null
  );
}

function buildPreferenceRecords({
  payload,
  identifier,
  identifierName,
  partition,
  defaultPurpose,
}) {
  const timestamp = new Date().toISOString();
  const updates = Array.isArray(payload?.preferenceUpdates)
    ? payload.preferenceUpdates
    : [payload];

  return updates
    .map((update) => {
      const purpose = update?.purpose || defaultPurpose;
      const enabled = toBoolean(update?.enabled, true);
      const preferences = mapTopicChoices(update?.preferences);

      return {
        userId: identifier,
        partition,
        timestamp,
        identifiers: [{ name: identifierName, value: identifier }],
        purposes: [
          {
            purpose,
            enabled,
            ...(preferences.length > 0 ? { preferences } : {}),
          },
        ],
        metadata: [
          {
            key: 'source',
            value: String(update?.source || 'external-system'),
          },
        ],
      };
    })
    .filter(Boolean);
}

function mapTopicChoices(input) {
  if (!Array.isArray(input)) {
    return [];
  }

  return input
    .map((item) => {
      if (
        !item ||
        !item.topic ||
        item.value === undefined ||
        item.value === null
      ) {
        return null;
      }

      if (Array.isArray(item.value)) {
        return {
          topic: item.topic,
          choice: { selectValues: item.value.map(String) },
        };
      }

      if (typeof item.value === 'boolean') {
        return {
          topic: item.topic,
          choice: { booleanValue: item.value },
        };
      }

      return {
        topic: item.topic,
        choice: { selectValue: String(item.value) },
      };
    })
    .filter(Boolean);
}

function toBoolean(value, fallback) {
  if (typeof value === 'boolean') {
    return value;
  }

  if (typeof value === 'string') {
    if (value.toLowerCase() === 'true') {
      return true;
    }
    if (value.toLowerCase() === 'false') {
      return false;
    }
  }

  return fallback;
}

{
  "vendor": {
    "name": "Acme Analytics Inc.",
    "description": "Product analytics and session replay for marketing sites.",
    "externalId": "VRM-2026-0042",
    "website": "https://www.acme-analytics.example",
    "headquartersCountry": "US",
    "headquartersSubdivision": "US-CA",
    "address": "100 Market St, San Francisco, CA 94105",
    "dpaUrl": "https://www.acme-analytics.example/legal/dpa",
    "dpaStatus": "CUSTOM_DPA",
    "businessEntity": "Engineering"
  },
  "requester": {
    "name": "Jordan Lee",
    "email": "jordan.lee@yourcompany.com",
    "team": "Procurement"
  },
  "approval": {
    "approvedBy": "alex.approver@yourcompany.com",
    "riskTier": "Medium"
  }
}

export default async function ({ payload, environment, sdk }) {
  const apiKey = environment.TRANSCEND_API_KEY;
  if (!apiKey) {
    throw new Error('Missing TRANSCEND_API_KEY environment variable');
  }

  async function graphql(query, variables) {
    const res = await sdk.fetch('/graphql', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ query, variables }),
    });

    const body = await res.json();

    if (!res.ok || body.errors) {
      throw new Error(
        `Transcend GraphQL error (${res.status}): ${JSON.stringify(body.errors ?? body)}`,
      );
    }

    return body.data;
  }

  const vendor = payload.vendor ?? {};
  const requester = payload.requester ?? {};
  const approval = payload.approval ?? {};

  const { name } = vendor;
  if (!name) {
    throw new Error('payload.vendor.name is required');
  }

  const { createVendor } = await graphql(
    /* GraphQL */ `
      mutation RulesAutomationCreateVendor($input: CreateVendorInput!) {
        createVendor(input: $input) {
          vendor {
            id
            title
          }
        }
      }
    `,
    {
      input: {
        title: name,
        description:
          vendor.description ??
          `Imported from VRM (${vendor.externalId ?? 'no id'})`,
        websiteUrl: vendor.website,
        headquarterCountry: vendor.headquartersCountry,
        headquarterSubDivision: vendor.headquartersSubdivision,
        address: vendor.address,
        dataProcessingAgreementLink: vendor.dpaUrl,
        dataProcessingAgreementStatus: vendor.dpaStatus,
        contactName: requester.name,
        contactEmail: requester.email,
        businessEntityTitle: vendor.businessEntity,
        ownerEmails: [requester.email, approval.approvedBy].filter(Boolean),
        teamNames: requester.team ? [requester.team] : [],
        attributes: [
          {
            key: 'External Vendor ID',
            values: [vendor.externalId].filter(Boolean),
          },
          {
            key: 'Risk Tier',
            values: [approval.riskTier].filter(Boolean),
          },
          { key: 'Source', values: ['VRM Webhook'] },
        ].filter((a) => a.values.length > 0),
      },
    },
  );

  const vendorId = createVendor.vendor.id;
  console.log(`Created vendor ${vendorId} (${name})`);

  return { vendorId };
}