Send Shopify order updates on WhatsApp

// shopify-hmac.js
import crypto from "node:crypto";

export function isFromShopify(rawBody, hmacHeader) {
  const expected = crypto
    .createHmac("sha256", process.env.SHOPIFY_CLIENT_SECRET)
    .update(rawBody)
    .digest();
  const received = Buffer.from(hmacHeader ?? "", "base64");

  // timingSafeEqual throws on buffers of different length.
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

// server.js
import express from "express";
import { parsePhoneNumberFromString } from "libphonenumber-js";
import { isFromShopify } from "./shopify-hmac.js";

const FLOWNALLY_API = "https://api.flownally.com/v1";

// Template and body parameters for each Shopify topic.
const UPDATES = {
  "orders/create": (order) => ({
    template: "order_confirmed",
    parameters: [firstName(order), order.name],
  }),
  "orders/fulfilled": (order) => ({
    template: "order_shipped",
    parameters: [
      firstName(order),
      order.name,
      order.fulfillments?.[0]?.tracking_url || order.order_status_url,
    ],
  }),
};

const app = express();

app.post("/webhooks/shopify", express.raw({ type: "application/json" }), async (req, res) => {
  if (!isFromShopify(req.body, req.get("X-Shopify-Hmac-Sha256"))) {
    return res.sendStatus(401);
  }

  try {
    await sendOrderUpdate(req.get("X-Shopify-Topic"), JSON.parse(req.body));
    res.sendStatus(200);
  } catch (error) {
    // Any status other than 200 makes Shopify deliver the webhook again.
    res.sendStatus(error.retryable === false ? 200 : 503);
  }
});

app.listen(3000);

async function sendOrderUpdate(topic, order) {
  const update = UPDATES[topic]?.(order);
  const phoneNumber = orderPhone(order);
  if (!update || !phoneNumber) return;

  await flownally(
    "/messages",
    {
      inboxId: process.env.FLOWNALLY_INBOX_ID,
      recipient: { type: "phone", phoneNumber },
      content: {
        type: "template",
        template: {
          name: update.template,
          language: "en",
          components: [
            {
              type: "body",
              parameters: update.parameters.map((text) => ({ type: "text", text })),
            },
          ],
        },
      },
    },
    `shopify-order-${order.id}-${update.template}`,
  );
}

// Shopify phone numbers can be in national format, so parse them with the order's country.
function orderPhone(order) {
  const raw =
    order.phone ||
    order.customer?.phone ||
    order.shipping_address?.phone ||
    order.billing_address?.phone;
  const country = order.shipping_address?.country_code || order.billing_address?.country_code;
  const phone = raw ? parsePhoneNumberFromString(raw, country) : undefined;
  return phone?.isValid() ? phone.number : null;
}

function firstName(order) {
  return order.customer?.first_name || "there";
}

async function flownally(path, body, idempotencyKey) {
  const response = await fetch(`${FLOWNALLY_API}${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FLOWNALLY_API_TOKEN}`,
      "Content-Type": "application/json",
      ...(idempotencyKey && { "Idempotency-Key": idempotencyKey }),
    },
    body: JSON.stringify(body),
  });
  if (!response.ok) {
    throw Object.assign(new Error(`Flownally ${path} returned ${response.status}`), {
      status: response.status,
      retryable: response.status === 429 || response.status >= 500,
    });
  }
  return response.json();
}

{
  "type": "text",
  "text": {
    "body": "Hi Anna, order #1001 is packed and leaves the warehouse today."
  }
}

curl -X POST "https://api.flownally.com/v1/event-types" \
  -H "Authorization: Bearer $FLOWNALLY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order.shipped",
    "description": "Every item in the order was fulfilled.",
    "payloadSchema": {
      "orderNumber": { "type": "string" },
      "firstName": { "type": "string" },
      "trackingUrl": { "type": "string" }
    }
  }'

const EVENTS = {
  "orders/create": (order) => ({
    name: "order.confirmed",
    payload: {
      orderNumber: order.name,
      firstName: firstName(order),
      total: Number(order.total_price),
      currency: order.currency,
    },
  }),
  "orders/fulfilled": (order) => ({
    name: "order.shipped",
    payload: {
      orderNumber: order.name,
      firstName: firstName(order),
      trackingUrl: order.fulfillments?.[0]?.tracking_url || order.order_status_url,
    },
  }),
};

async function sendOrderUpdate(topic, order) {
  const event = EVENTS[topic]?.(order);
  const phone = orderPhone(order);
  if (!event || !phone) return;

  const contactId = await findOrCreateContact(phone, order);
  try {
    await flownally(`/contacts/${contactId}/events`, {
      ...event,
      idempotencyKey: `shopify-order-${order.id}-${event.name}`,
    });
  } catch (error) {
    // 409 means an event with this idempotency key was already recorded.
    if (error.status !== 409) throw error;
  }
}

async function findOrCreateContact(phone, order) {
  const { contacts } = await flownally("/contacts:search", {
    query: {
      match: "all",
      conditions: [
        { type: "customFieldText", fieldId: "cf_phone", operator: "equals", value: phone },
        { type: "archiveStatus", status: "all" },
      ],
    },
    pageSize: 1,
  });
  if (contacts.length > 0) return contacts[0].id;

  const name = [order.customer?.first_name, order.customer?.last_name].filter(Boolean).join(" ");
  const contact = await flownally("/contacts", { name, phone });
  return contact.id;
}