# Library event webhooks

*Collection: Downloads, Leads & Analytics · Category: Integrations · Availability: FileDeck Pro · Canonical URL: https://www.getfiledeck.com/docs/document-events/*

FileDeck can already tell you when a document is *downloaded*. Library event
webhooks tell you when the library itself **changes** — a document published,
updated, retired or permanently deleted.

That is the hook most integrations actually need. `document.published` arriving
in Zapier or Make is enough to post to Slack, add a row to a sheet, start a
newsletter, or sync into another system, without anyone polling your site.

> **FileDeck Pro** — set it up under **Documents → Settings → Downloads**.

## The events

| Event | Fires when |
|---|---|
| `document.published` | A document becomes published for the first time, or is republished |
| `document.updated` | An already-published document is saved again |
| `document.unpublished` | A published document becomes a draft, pending, or is trashed |
| `document.deleted` | A document is permanently deleted |
| `document.downloaded` | A document is downloaded |

Each is switched on individually — most integrations want one or two, not all
five.

## Setting it up

1. Go to **Documents → Settings → Downloads**.
2. Put your endpoint in **Library event webhook**. It must be `https`. To get the
   events as messages in a chat channel, paste a Slack incoming-webhook URL or a
   Microsoft Teams Workflows webhook URL here instead (see below).
3. Tick the events you want.
4. Save. FileDeck generates a **signing secret** for you automatically.

## Straight into Slack or Microsoft Teams

Paste a **Slack incoming-webhook URL** (`https://hooks.slack.com/services/…`) or a
**Microsoft Teams Workflows webhook URL** (from the "Post to a channel when a
webhook request is received" workflow) as the endpoint, and each event arrives as
a readable message: the document's title linked to its page and what happened to
it. Teams also gets an "Open document" button. Teams still receives the JSON
below alongside the card, so a flow you built around those fields keeps working.
Slack Workflow Builder trigger URLs (`hooks.slack.com/triggers/…`) get the JSON as
before, for workflows whose variables are defined against it. Teams' older
"Incoming Webhook" connector URLs are retired by Microsoft and are not recognised.

## The payload

```json
{
  "event": "document.published",
  "occurred_at": "2026-07-25T09:14:02+00:00",
  "site": "https://example.com/",
  "document": {
    "id": 4182,
    "title": "Safeguarding Policy 2026",
    "status": "publish",
    "permalink": "https://example.com/document/safeguarding-policy-2026/",
    "file_type": "pdf",
    "file_size": 284119,
    "downloads": 0,
    "categories": ["policies"],
    "tags": ["safeguarding"],
    "restricted": false
  }
}
```

The payload **describes** the document — it never contains the file or its
extracted text. A webhook endpoint is an unauthenticated third party as far as
your site is concerned, so it gets identifiers and metadata. The permalink is
just a link: normal access control still applies to anyone who follows it, so a
restricted document does not become public by being announced.

## Verifying the signature

Every delivery is signed so your endpoint can prove the request came from your
site rather than from anyone who guessed the URL. These headers are sent:

| Header | Meaning |
|---|---|
| `X-FileDeck-Event` | The event key |
| `X-FileDeck-Delivery` | Unique id for this delivery — use it to de-duplicate |
| `X-FileDeck-Timestamp` | Unix seconds, included in the signed material |
| `X-FileDeck-Signature` | `sha256=` followed by the HMAC |
| `X-FileDeck-Version` | The FileDeck version that sent it |

The signature is an HMAC-SHA256 over **the timestamp, a dot, and the raw request
body**, keyed with your signing secret:

```python
import hmac, hashlib

def verify(secret, timestamp, raw_body, header):
    expected = "sha256=" + hmac.new(
        secret.encode(), f"{timestamp}.{raw_body}".encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)
```

Sign against the **raw** body, before any JSON parsing — re-serialising changes
the bytes and the signature will not match. Because the timestamp is inside the
signed material, a captured delivery cannot be replayed later with a fresh one;
reject anything older than a few minutes.

## Reliability

Deliveries are **non-blocking and best-effort**. A webhook must never be able to
slow down or fail a document save, so FileDeck fires and moves on — it does not
wait for your response, and it does not retry. If your endpoint needs
at-least-once delivery, reconcile periodically against the library rather than
relying on every POST arriving.

## Testing it

With WP-CLI, fire a real event at your endpoint without publishing anything:

```
wp filedeck event test --event=document.published --id=4182
```

## Building on it in PHP

Every event also fires a WordPress action, whether or not a webhook is
configured:

```php
add_action( 'filedeck_event', function ( $event, $payload ) {
    if ( 'document.published' === $event ) {
        // …
    }
}, 10, 2 );
```

Use `filedeck_event_payload` to add fields to what is sent.

## FAQ

### Can I send to more than one endpoint?

One URL is configured in the settings. For several destinations, point it at
Zapier, Make or a small script that fans out — or hook `filedeck_event` in PHP.

### Why is my http:// URL rejected?

Event payloads name documents, categories and restriction state, which is not
public information on a gated library, so FileDeck refuses to send them in
cleartext. Use `https`.

### What if I clear the signing secret?

Deliveries still go out, unsigned, and your endpoint loses any way to verify
them. Keep the secret unless you have a specific reason not to.
