Webhooks API overview for DocInject

Webhooks let your server receive automatic notifications when activity occurs in your DocInject organization. When a subscribed event fires, such as a document being published, a member joining, or a role changing, DocInject sends an HTTP POST request to your registered URL with a signed JSON payload.

Webhook integrations require the Scale plan. Attempting to register a webhook on a lower-tier plan returns 403.

Payload envelope

Every webhook request shares the same top-level structure regardless of event type.

{
  "event_type": "document.published",
  "organization_id": "a1b2c3d4-0000-0000-0000-111122223333",
  "org_slug": "acme-ops",
  "occurred_at": "2024-01-15T10:30:00Z",
  "data": { ... }
}

event_type

string

required

The name of the event that fired. See Event reference for all possible values.

organization_id

string

required

UUID of the organization that generated the event.

org_slug

string

required

URL-safe slug for the organization (e.g. acme-ops).

occurred_at

string

required

ISO 8601 timestamp marking when the event was dispatched.

data

object

required

Event-specific payload. Shape varies by event_type; see the event reference for full schemas.

Verifying signatures

DocInject signs every request with HMAC-SHA256. The signature is included in the X-DocInject-Signature header as sha256=<hex-digest>. Your webhook secret is returned once when you register a webhook (POST /webhooks). Store it securely. It is not retrievable afterwards. To verify a request:

Read the raw request body

Compute the signature over the raw bytes before any JSON parsing.

Compute the expected signature

HMAC-SHA256 the raw body using your webhook secret.

Compare signatures

Use a constant-time comparison to check that your computed digest matches the sha256= value in the header. Reject the request if they do not match.

import { createHmac, timingSafeEqual } from "crypto";

function verifySignature(rawBody, secret, signatureHeader) {
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader ?? "");
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

Delivery behavior

DocInject attempts delivery up to 3 times with exponential backoff (delays of 1 s and 2 s between retries). Your endpoint must return a 2xx response within 10 seconds. Non-2xx responses and network errors are both treated as delivery failures.

​Payload envelope

​Verifying signatures

​Delivery behavior

Payload envelope

Verifying signatures

Delivery behavior