Docs menu

Analytics and notifications

Webhooks and Slack

Send room activity to a Slack channel or to your own systems, with signed requests and automatic retries.

Add an endpoint

Owners and admins can send room activity to two kinds of destination. Each one is called an endpoint, and each gets only the events you tick for it.

Slack
Posts a short message to one Slack channel for each event.
Webhook
Sends a signed JSON request to any HTTPS address you control, such as your CRM or an automation tool.

Slack

  1. In Slack, create an incoming webhook for the channel (Apps → Incoming Webhooks) and copy its URL. It starts with https://hooks.slack.com/services/.
  2. In undocsend, go to Settings → Webhooks and click Add endpoint.
  3. Choose Slack, give it a Name such as #deal-activity, and paste the URL.
  4. Untick any events you don’t want, then click Save endpoint.
  5. Click Send test event and check the channel.

Webhook

  1. Go to Settings → Webhooks and click Add endpoint.
  2. Choose Webhook, give it a Name, and paste your URL.
  3. Choose events and click Save endpoint.
  4. Copy the signing secret (it starts with whsec_) and click Done. It is shown only once. If you lose it, rotate it.
  5. Click Send test event. Your endpoint receives a webhook.test event.

The URL must:

  • Start with https:// and use the standard port.
  • Point to a public address. Private, local and internal addresses are refused.
  • Not contain a username or password.

URLs and secrets are stored encrypted. After saving, undocsend only ever shows the end of the URL and the last four characters of the secret.

Events

Room opened room.opened
A visitor’s first document open of the day, with the room it was in. Sent once per visitor per day, and not sent when that first open is through a share link.
Document viewed document.viewed
A visitor opens a document.
Agreement signed agreement.signed
A visitor signs or accepts an NDA or other room agreement.
Question asked question.asked
A visitor asks the room assistant or the team a question.
Question answered question.answered
Someone on your team approves an answer and it is emailed to the visitor who asked.
File uploaded file.uploaded
A visitor uploads a file against a document request. It waits for your review before it appears in the room.
Share link created share_link.created
Someone on your team creates a share link.

New endpoints start with every event ticked.

What a webhook receives

Each event is a POST with a JSON body. Slack endpoints get a formatted message instead.

Example body
{
  "id": "evt_0b0c5d1e-8f43-4c51-9a7e-2f0b1c9d3e44",
  "type": "document.viewed",
  "created_at": "2026-10-08T14:03:11.204Z",
  "workspace": { "id": "4f1…", "slug": "acme" },
  "data": {
    "room": { "id": "…", "name": "Series A", "slug": "series-a" },
    "document": { "id": "…", "name": "Deck.pdf" },
    "visitor": { "id": "…", "email": "jane@example.com", "name": "Jane Doe" }
  }
}

data holds the records the event is about: room, document, visitor, agreement, and extra fields for some events, such as question and answer (first 500 characters each), share_link, share_link_id for a view or signature through a share link, or upload. A record that no longer exists is null. Views through a share link have room set to null.

Webhooks never include IP addresses, browser details or document content.

Headers

Content-Type
application/json
User-Agent
undocsend-webhooks/1.0
X-Undocsend-Event
The event type.
X-Undocsend-Event-Id
The body’s id. It stays the same on every retry, so use it to ignore duplicates.
X-Undocsend-Delivery
The id of this delivery to this endpoint.
X-Undocsend-Signature
t=<unix seconds>,v1=<signature>

Verify the signature

Check every request before you trust it:

  1. Read t and v1 from the X-Undocsend-Signature header.
  2. Reject the request if t is more than 5 minutes from now.
  3. Compute HMAC-SHA256 of <t>.<raw body>, using your whole secret (including whsec_) as the key, and hex-encode it.
  4. Compare it with v1 in constant time. Use the raw body exactly as received, not re-serialised JSON.
Node.js
import { createHmac, timingSafeEqual } from 'node:crypto'

export function verifyUndocsend(rawBody: string, header: string | null, secret: string): boolean {
  if (!header) return false
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=', 2)))
  const t = Number(parts.t)
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  const got = Buffer.from(String(parts.v1 ?? ''))
  return got.length === expected.length && timingSafeEqual(got, Buffer.from(expected))
}

Reply with any 2xx status within 10 seconds, and do slow work afterwards. Slack messages are not signed.

Retries and automatic turn-off

  • Any status other than 2xx, a timeout, a connection error or a redirect counts as a failure. Redirects are never followed.
  • Each event is tried up to 6 times: at once, then after 1, 4, 16, 64 and 256 minutes, about six hours in all.
  • After 20 failed attempts in a row, the endpoint is turned off and its waiting deliveries are cancelled. Your notification recipients get one email: “Webhook endpoint ‘[name]’ was turned off”. If you have no recipients, the person who created the endpoint gets it.
  • Turning the endpoint back on resets the failure count.
  • Send test event works while an endpoint is off, and test sends never count as failures. Use it to check your fix before you turn the endpoint back on.

Sandbox workspaces don’t send automatic events. Test events still go out.

Manage endpoints

Each endpoint in the list shows its status, the end of its URL, the last four characters of its secret, its events, and how many failures in a row it has had. Turned off after failures means it was turned off automatically.

  • Use the switch to turn an endpoint on or off.
  • Click Edit to change the Name or events (then Save changes), paste a new address under Replace URL, or click Rotate signing secret. The old secret stops working immediately.
  • Delete endpoint removes it and its delivery history.

Recent deliveries lists the latest 30 deliveries with When, Endpoint, Event, Status (Delivered, Failed, or Retrying with the next try time), Attempts and Result (the HTTP status or error). Delivery history is kept for 30 days.