Scribe webhook use cases: sync conversions, alert on failed installs

import express from "express";
import { Webhook } from "svix";

const app = express();
const wh = new Webhook(process.env.SCRIBE_WEBHOOK_SECRET);

// Verification needs the raw body, so do not parse JSON before it.
app.post("/webhooks/scribe", express.raw({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = wh.verify(req.body, req.headers);
  } catch {
    return res.sendStatus(400);
  }

  // Acknowledge first. Retries are expensive for both sides.
  res.sendStatus(200);

  // svix-id is stable across retries of the same message: use it to deduplicate.
  await queue.add("scribe-event", { id: req.headers["svix-id"], event });
});

async function onConversionRecorded(event, deliveryId) {
  const { visitor, attribution, properties } = event;

  await crm.upsertOpportunity({
    // event_id is the idempotency key you passed when tracking. It can be null,
    // so fall back to the svix-id of the delivery.
    externalId: event.event_id ?? deliveryId,
    contactExternalId: visitor.user_id,
    name: event.name,
    amount: event.value,
    currency: event.currency,
    closedAt: event.occurred_at,
    source: "Email signature",
    ownerUuid: attribution.teammate_uuid || null,
    campaignUuid: attribution.marketing_campaign_uuid || null,
    plan: properties?.plan,
  });
}

import { createHash } from "node:crypto";

// Both platforms expect SHA-256 of the trimmed, lowercased address.
const hashEmail = (email) => createHash("sha256").update(email.trim().toLowerCase()).digest("hex");

async function onVisitorIdentified(event) {
  const email = event.visitor.traits?.email;
  if (!email) return;

  // Only upload people whose consent covers advertising audiences.
  if (!(await consent.allowsAdvertising(email))) return;

  const hashedEmail = hashEmail(email);

  await Promise.all([
    googleAds.customerMatch.add({
      userListId: process.env.GOOGLE_ADS_USER_LIST_ID,
      hashedEmail,
    }),
    meta.customAudiences.add({
      audienceId: process.env.META_AUDIENCE_ID,
      schema: ["EMAIL_SHA256"],
      data: [[hashedEmail]],
    }),
  ]);
}

async function suppressConverted(event) {
  const person = await db.people.findByUserId(event.visitor.user_id);
  if (!person?.email) return;

  const hashedEmail = hashEmail(person.email);

  await Promise.all([
    googleAds.customerMatch.remove({
      userListId: process.env.GOOGLE_ADS_USER_LIST_ID,
      hashedEmail,
    }),
    googleAds.customerMatch.add({
      userListId: process.env.GOOGLE_ADS_CONVERTED_LIST_ID,
      hashedEmail,
    }),
  ]);
}

async function onInstallationFailed(event) {
  const { email, signature, integration, error_code } = event;

  await fetch(process.env.SLACK_WEBHOOK_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: [
        `Signature install failed for *${email.address}*`,
        `Template: ${signature.name} (${signature.kind})`,
        `Integration: ${integration.kind}`,
        `Reason: \`${error_code}\``,
      ].join("\n"),
    }),
  });
}

async function onIntegrationAccessLost(event) {
  const { integration, error_message, reconnect_url } = event;

  await pagerduty.trigger({
    summary: `Scribe lost access to ${integration.name}`,
    severity: integration.category === "signatures" ? "error" : "warning",
    details: error_message,
    links: [{ href: reconnect_url, text: "Reconnect in Scribe" }],
  });
}

async function onTeammateEvent(event) {
  const primary = event.emails.find((e) => e.primary) ?? event.emails[0];

  if (event.type === "teammate.created") {
    await itsm.createTask({
      title: `Onboarding: ${event.teammate.display_name}`,
      assignee: "it-team",
      body: `Scribe teammate created for ${primary.address}. Confirm their signature installs.`,
    });
    return;
  }

  // teammate.deleted is your last chance to read their identifiers.
  await directory.markOffboarded({
    teammateUuid: event.teammate.uuid,
    email: primary.address,
    offboardedAt: event.occurred_at,
  });
}

const CAMPAIGN_EVENTS = new Set([
  "campaign.scheduled",
  "campaign.started",
  "campaign.paused",
  "campaign.resumed",
  "campaign.ended",
]);

async function onCampaignEvent(event) {
  if (!CAMPAIGN_EVENTS.has(event.type)) return;
  const { campaign } = event;

  if (event.type === "campaign.started" || event.type === "campaign.ended") {
    await analytics.createAnnotation({
      label: `${campaign.name} ${event.type === "campaign.started" ? "live" : "ended"}`,
      timestamp: event.occurred_at,
      templates: campaign.signature_template_uuids,
    });
  }

  await slack.post("#marketing", `${campaign.name} is now ${campaign.status}`);
}