Getting Started

# Read your credentials from the environment - never paste an API key
# into a shell command, where it lands in your history and process list.
#   export MOCHA_TENANT=...
#   export MOCHA_API_KEY=...

curl -X POST \
  'https://services.us.uat.mochatechnologies.com/signature/api/V1/get-template-by-user' \
  -H "X-Tenant: $MOCHA_TENANT" \
  -H "Api-Key: $MOCHA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "user_id": "acf28c4584f007dca67b" }'

# Read your credentials from the environment - never paste an API key
# into a shell command, where it lands in your history and process list.
#   export MOCHA_TENANT=...
#   export MOCHA_API_KEY=...

curl -X POST \
  'https://services.us.uat.mochatechnologies.com/signature/api/V1/get-template-by-user' \
  -H "X-Tenant: $MOCHA_TENANT" \
  -H "Api-Key: $MOCHA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "user_id": "acf28c4584f007dca67b" }'

<?php

$baseUrl = 'https://services.us.uat.mochatechnologies.com/signature/api/V1';
$payload = json_encode(['user_id' => 'acf28c4584f007dca67b']);

$ch = curl_init($baseUrl . '/get-template-by-user');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        'X-Tenant: ' . getenv('MOCHA_TENANT'),
        'Api-Key: '  . getenv('MOCHA_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => $payload,
]);

$response = curl_exec($ch);
$status   = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// The HTTP status code is authoritative - branch on it, not on the body.
if ($status !== 200) {
    throw new RuntimeException('Mocha Signature returned ' . $status . ': ' . $response);
}

$templates = json_decode($response, true)['data'] ?? [];

const BASE_URL =
  "https://services.us.uat.mochatechnologies.com/signature/api/V1";

async function callMochaSignature(endpoint, body) {
  const response = await fetch(BASE_URL + endpoint, {
    method: "POST",
    headers: {
      "X-Tenant": process.env.MOCHA_TENANT,
      "Api-Key": process.env.MOCHA_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  const payload = await response.json();

  if (!response.ok) {
    throw new Error(
      "Mocha Signature " + response.status + ": " + JSON.stringify(payload),
    );
  }

  return payload;
}

const { data: templates } = await callMochaSignature("/get-template-by-user", {
  user_id: "acf28c4584f007dca67b",
});

import os
import requests

BASE_URL = "https://services.us.uat.mochatechnologies.com/signature/api/V1"
HEADERS = {
    "X-Tenant": os.environ["MOCHA_TENANT"],
    "Api-Key": os.environ["MOCHA_API_KEY"],
    "Content-Type": "application/json",
}

response = requests.post(
    BASE_URL + "/get-template-by-user",
    headers=HEADERS,
    json={"user_id": "acf28c4584f007dca67b"},
    timeout=30,
)
response.raise_for_status()

templates = response.json()["data"]

// 1. Read the template so you know exactly which roles it expects.
const detail = await callMochaSignature("/get-template-detail", {
  template_id: "73766101002022",
});

const { required_recipient, recipients_role } = detail.data;
// required_recipient: 2
// recipients_role:   ["Signer 1", "Approver"]

// 2. Send the envelope. One entry per role, in the template's own order.
const sent = await callMochaSignature("/send-envelop", {
  user_id: "acf28c4584f007dca67b",
  company_name: "Your Company",
  email_subject: "Please sign the Non-Disclosure Agreement",
  message: "Kindly review and sign the attached document.",
  template_id: "73766101002022",
  recipients_role: [
    { role: "Signer 1", name: "John Doe", email: "john.doe@example.com" },
    { role: "Approver", name: "Alice Smith", email: "alice.smith@example.com" },
  ],
  metadata: { order_id: "ORD-10021", source: "crm" },
});

// 3. Persist envelope_id - it is the key for tracking and for every webhook.
await db.orders.update("ORD-10021", { envelopeId: sent.envelope_id });

// 4. Poll tracking when you need the current state (webhooks push the final one).
const tracking = await callMochaSignature("/envelop-tracking", {
  envelop_id: sent.envelope_id,
});

{
  "status": false,
  "msg": {
    "template_id": ["The template id field is required."]
  }
}

{
  "event": "document.completed",
  "data": {
    "user_id": "acf28c4584f007dca67b",
    "envelop_id": "b5db5fe9-8a44-4ecc-b3f4-222b14b1d5dc",
    "status": "completed",
    "generated_at": "2026-08-03T10:24:11.000000Z",
    "metadata": {
      "order_id": "ORD-10021",
      "source": "crm"
    },
    "document": {
      "file_name": "b5db5fe9-8a44-4ecc-b3f4-222b14b1d5dc.pdf",
      "download_url": "https://s3.amazonaws.com/...?X-Amz-Expires=900&X-Amz-Signature=...",
      "mime_type": "application/pdf"
    }
  },
  "timestamp": "2026-08-03T10:24:11.482000Z"
}

<?php

// Read the RAW body. Re-encoding the JSON changes the digest.
$rawBody = file_get_contents('php://input');

$incomingSignatures = [
    $_SERVER['HTTP_X_WEBHOOK_SIGNATURE_1'] ?? null,
    $_SERVER['HTTP_X_WEBHOOK_SIGNATURE_2'] ?? null,
];

// Load the secret from configuration - never hard-code it in the handler.
$secret   = getenv('MOCHA_WEBHOOK_SECRET');
$computed = base64_encode(hash_hmac('sha256', $rawBody, $secret, true));

$valid = false;
foreach ($incomingSignatures as $signature) {
    if ($signature && hash_equals($computed, $signature)) {
        $valid = true;
        break;
    }
}

if (!$valid) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($rawBody, true);

// Acknowledge immediately, then process out of band.
http_response_code(200);
echo json_encode(['received' => true]);

const crypto = require("crypto");
const express = require("express");

const app = express();

// Your active secret keys - up to two while rotating.
const SECRETS = [
  process.env.MOCHA_WEBHOOK_SECRET_1,
  process.env.MOCHA_WEBHOOK_SECRET_2,
].filter(Boolean);

function isValidSignature(rawBody, headers) {
  const incoming = [
    headers["x-webhook-signature-1"],
    headers["x-webhook-signature-2"],
  ].filter(Boolean);

  return incoming.some((signature) =>
    SECRETS.some((secret) => {
      const computed = crypto
        .createHmac("sha256", secret)
        .update(rawBody)
        .digest("base64");

      const a = Buffer.from(computed);
      const b = Buffer.from(signature);
      return a.length === b.length && crypto.timingSafeEqual(a, b);
    }),
  );
}

// express.raw keeps the exact bytes - never verify JSON.stringify(req.body).
app.post(
  "/hooks/mocha-signature",
  express.raw({ type: "application/json" }),
  (req, res) => {
    if (!isValidSignature(req.body, req.headers)) {
      return res.status(401).send("Invalid signature");
    }

    const event = JSON.parse(req.body.toString("utf8"));

    res.sendStatus(200);            // acknowledge fast
    queue.add("mocha-signature", event); // process asynchronously
  },
);