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
- In Slack, create an incoming webhook for the channel (Apps → Incoming Webhooks) and copy its URL. It starts with
https://hooks.slack.com/services/. - In undocsend, go to Settings → Webhooks and click Add endpoint.
- Choose Slack, give it a Name such as
#deal-activity, and paste the URL. - Untick any events you don’t want, then click Save endpoint.
- Click Send test event and check the channel.
Webhook
- Go to Settings → Webhooks and click Add endpoint.
- Choose Webhook, give it a Name, and paste your URL.
- Choose events and click Save endpoint.
- Copy the signing secret (it starts with
whsec_) and click Done. It is shown only once. If you lose it, rotate it. - Click Send test event. Your endpoint receives a
webhook.testevent.
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.
{
"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-Typeapplication/jsonUser-Agentundocsend-webhooks/1.0X-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-Signaturet=<unix seconds>,v1=<signature>
Verify the signature
Check every request before you trust it:
- Read
tandv1from theX-Undocsend-Signatureheader. - Reject the request if
tis more than 5 minutes from now. - Compute HMAC-SHA256 of
<t>.<raw body>, using your whole secret (includingwhsec_) as the key, and hex-encode it. - Compare it with
v1in constant time. Use the raw body exactly as received, not re-serialised JSON.
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.