---
title: "Webhooks and Slack"
description: "Send room activity to a Slack channel or to your own systems, with signed requests and automatic retries."
canonical: "https://undocsend.com/docs/analytics/webhooks"
last_updated: "2026-11-19"
---

# 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.

---

Section: Analytics and notifications. HTML: https://undocsend.com/docs/analytics/webhooks · Docs index: https://undocsend.com/docs.md
