Skip to content

Cookbook

Notify Slack or Microsoft Teams about signing events

Post a message to a Slack or Microsoft Teams channel when an envelope completes or fails, or when a recipient rejects it.

Tell your team when something needs attention. The handler verifies the webhook, then posts one short message for envelope.completed, recipient.rejected and envelope.failed.

What you need

  • A webhook endpoint subscribed to those three events. See Set up webhooks.
  • For Slack, an incoming webhook URL in SLACK_WEBHOOK_URL. Treat it as a secret: Slack notes it acts as a credential. Source: Sending messages using incoming webhooks.
  • For Teams, a workflow webhook URL in TEAMS_WEBHOOK_URL. Microsoft retired Office 365 connectors in Teams in May 2026 and points to the Workflows app instead, for example the Send webhook alerts to a channel template. Source: Create an Incoming Webhook.
  • SIGNATUREAPI_WEBHOOK_SECRET.

The handler

Both tabs build the same text from the event. The messages carry the envelope id and your own envelope_metadata, never signer emails. Replace deal_id with a key you set on your envelopes.

Slack
import express from "express";
import { Webhook } from "standardwebhooks";

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

function describe({ type, data }) {
  const deal = data.envelope_metadata?.deal_id ?? "unknown deal";
  switch (type) {
    case "envelope.completed":
      return `Envelope signed. Deal ${deal} (envelope ${data.envelope_id}).`;
    case "recipient.rejected":
      return `Recipient "${data.recipient_key}" rejected deal ${deal} (envelope ${data.envelope_id}): ${data.reason || "no reason given"}`;
    case "envelope.failed":
      return `Envelope failed. Deal ${deal} (envelope ${data.envelope_id}): ${data.detail}`;
    default:
      return null;
  }
}

app.post("/webhooks/signatureapi", express.raw({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = wh.verify(req.body.toString("utf8"), req.headers);
  } catch {
    return res.sendStatus(400);
  }
  const text = describe(event);
  if (text) {
    const post = await fetch(process.env.SLACK_WEBHOOK_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ text }),
    });
    if (!post.ok) return res.sendStatus(502); // SignatureAPI retries
  }
  res.sendStatus(200);
});

app.listen(3000);
Teams
import express from "express";
import { Webhook } from "standardwebhooks";

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

function describe({ type, data }) {
  const deal = data.envelope_metadata?.deal_id ?? "unknown deal";
  switch (type) {
    case "envelope.completed":
      return `Envelope signed. Deal ${deal} (envelope ${data.envelope_id}).`;
    case "recipient.rejected":
      return `Recipient "${data.recipient_key}" rejected deal ${deal} (envelope ${data.envelope_id}): ${data.reason || "no reason given"}`;
    case "envelope.failed":
      return `Envelope failed. Deal ${deal} (envelope ${data.envelope_id}): ${data.detail}`;
    default:
      return null;
  }
}

app.post("/webhooks/signatureapi", express.raw({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = wh.verify(req.body.toString("utf8"), req.headers);
  } catch {
    return res.sendStatus(400);
  }
  const text = describe(event);
  if (text) {
    const post = await fetch(process.env.TEAMS_WEBHOOK_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        type: "message",
        attachments: [
          {
            contentType: "application/vnd.microsoft.card.adaptive",
            content: {
              $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
              type: "AdaptiveCard",
              version: "1.2",
              body: [{ type: "TextBlock", text, wrap: true }],
            },
          },
        ],
      }),
    });
    if (!post.ok) return res.sendStatus(502); // SignatureAPI retries
  }
  res.sendStatus(200);
});

app.listen(3000);
  • Verify first. Anyone can POST to your endpoint, so check the signature over the raw body before you post anything. See verify the signature.
  • Failures and duplicates. SignatureAPI retries a non-2XX response for up to 48 hours, and the same event can arrive more than once. Returning 502 when the chat post fails gets you a retry, and a retry can post the message twice. To post once, remember the event id and skip repeats.
  • Reason text. data.reason is what the recipient typed, and it is an empty string when they gave none. It is free text from the signer, so post it as plain message text only.
  • Teams format. Workflows webhooks accept Adaptive Card payloads like the one above. Microsoft documents a 28 KB message limit and throttling above four requests per second. Workflows belong to their owner, so add a co-owner to keep the webhook alive when someone leaves.
  • Link to the envelope. The messages carry only the envelope id. Open the envelope in the Dashboard or fetch it with the API using that id.