Docvora Documentation
Docvora Website Features Pricing Contact Us
Get 50% off your first three months for a limited time! Find out more.
API & Integrations IconAPI & Integrations

Webhook Payloads & Verification

By Docvora Assistant 5 mins 6

Webhooks set to JSON (signed) send a JSON request to the webhook's URL each time a matching event happens. This page shows what those requests contain and how to check they came from Docvora. It's intended for teams connecting webhooks to their own apps, or to automation tools such as Zapier, Make and n8n.

Discord and Slack webhooks are sent as messages in those services' own formats, so they don't need any of the steps below.

Webhooks are available on Pro and Enterprise plans. Creating and managing webhooks requires the Webhooks staff permission. See Webhooks for creating a webhook.


Events

Each request has a type with one of these events:

  • page.created: a page was created

  • page.updated: a page's content or settings changed

  • page.deleted: a page was deleted

  • page.archived: a page was archived

  • page.restored: an archived page was restored

  • ping: a test sent with the Send test button

Saving a page without changing anything doesn't send an event.


Example request

{
  "type": "page.updated",
  "timestamp": "2026-11-12T03:15:42.000Z",
  "data": {
    "site": {
      "name": "Acme Docs",
      "url": "https://docs.example.com"
    },
    "actor": {
      "id": "284019553376034816",
      "username": "Sam"
    },
    "space": {
      "id": "281397012381270016",
      "name": "Getting Started",
      "url": "https://docs.example.com/spaces/getting-started"
    },
    "page": {
      "id": "292551585216049152",
      "name": "Creating an account",
      "link": "creating-an-account",
      "url": "https://docs.example.com/spaces/getting-started/creating-an-account",
      "shortUrl": "https://docs.example.com/p/292551585216049152",
      "parentpage": null,
      "hidden": false,
      "archived": false,
      "readtime": 3,
      "summary": "Accounts can be created with an email address or a connected Google account...",
      "createdAt": 1760000000000,
      "updatedAt": 1762917342000
    },
    "changes": {
      "name": {
        "from": "Creating your account",
        "to": "Creating an account"
      }
    },
    "contentChanged": true
  }
}

Request fields

  • type: the event, from the list above.

  • timestamp: when the event happened, in ISO 8601 format.

  • data.site: the site's name and address.

  • data.actor: the account that made the change. It's null when there isn't one, such as for test events.

  • data.space: the page's space, with its ID, name and address.

  • data.page: the page's details. summary is the start of the page's text, up to 280 characters. createdAt and updatedAt are in milliseconds since 1 January 1970 (UTC).

  • data.changes: on page.updated, each setting that changed, with its old and new value. Settings include the page's name, address, search keywords, space, parent page, page width, visibility, pinned state and groups.

  • data.contentChanged: on page.updated, whether the page's content changed.

  • data.published: included as true when a hidden page was made visible.

Page content

When Include page content is turned on for the webhook, data.page.content is added to every event except page.deleted:

  • html: the page's content as HTML

  • markdown: the page's content as Markdown

  • text: the page's content as plain text

Hidden and restricted pages

Events about hidden pages, pages restricted to groups, and pages in hidden or restricted spaces are only sent when Include hidden and restricted pages is turned on for the webhook.


Headers

Every JSON request is sent as a POST with these headers:

  • Content-Type: application/json

  • webhook-id: a unique ID for the delivery. Retries of the same delivery keep the same ID, so it can be used to ignore duplicates.

  • webhook-timestamp: when the request was sent, in seconds since 1 January 1970 (UTC).

  • webhook-signature: the signature used to verify the request.


Verifying requests

Requests are signed with the webhook's signing secret using the Standard Webhooks format. Checking the signature confirms that a request came from Docvora and wasn't changed on the way.

The signing secret is shown on the webhook's page under Staff Panel > Integrations > Webhooks. It starts with whsec_ and should be kept private.

Using a Standard Webhooks library

Standard Webhooks libraries are available for most languages. In Node.js:

// npm install standardwebhooks
const {Webhook} = require('standardwebhooks');
const wh = new Webhook(process.env.WEBHOOK_SECRET);

// Use the raw request body, before it's parsed as JSON
const event = wh.verify(rawBody, request.headers); // throws if the signature is wrong
console.log(event.type, event.data.page.name);

Checking the signature by hand

  1. Take the part of the secret after whsec_ and decode it from base64. This is the signing key.

  2. Join the webhook-id header, the webhook-timestamp header and the raw request body with full stops: id.timestamp.body.

  3. Create an HMAC-SHA256 of that text using the signing key, and encode the result as base64.

  4. Compare it with the webhook-signature header, which is written as v1, followed by the signature.

It's also good practice to reject requests where webhook-timestamp is more than five minutes old.

Changing the secret

Select Create a new secret on the webhook's page to replace the secret. The old secret stops working straight away, so update the receiving app at the same time.


Responding to requests

The receiving app should respond with any 2xx status code, such as 200, within 10 seconds.

  • Any other response, or no response, counts as a failed delivery and is retried.

  • Retries happen after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours, for about two days in total.

  • A 429 response with a Retry-After header is retried after the time requested.

  • A 410 response turns the webhook off straight away, as it tells Docvora the receiver no longer exists.

  • After 30 failed attempts in a row, the webhook turns itself off.

Test events from Send test are sent once and aren't retried.

Recent deliveries

The webhook's page lists the last 50 deliveries from the past 30 days, with the request that was sent and the response that came back. Any delivery can be sent again from this list.