Webhooks

Slate webhooks push event data to your server the moment something happens in our system, so you never need to poll for updates. When a subscribed event occurs, Slate sends an HTTP POST request to your registered endpoint with a JSON payload describing the event.

Getting started

Build a webhook endpoint

Create an HTTPS endpoint on your server that accepts POST requests and returns a 200 OK response. The endpoint must be publicly reachable and support TLS. Return a 2xx before performing any slow processing. If there is additional processing needed, use a queue internally if needed.

Send your endpoint URL to your Slate integration contact. We’ll provision your webhook and return a HMAC-SHA256 signing secret used to verify that every delivery came from Slate.

Verify signatures and process events

On each incoming request, verify the svix-signature header using your signing secret before trusting the payload. Then act on the event type and matter data in the body.

Receiving events

Slate delivers every event as an HTTP POST to your registered endpoint.

Request headers

Header	Description
`svix-id`	Unique identifier for this message. Stable across retry attempts — use it for idempotency.
`svix-timestamp`	Unix timestamp (seconds) of when the message was sent. Reject messages with timestamps older than 5 minutes to guard against replay attacks.
`svix-signature`	One or more HMAC-SHA256 signatures of the payload, space-separated, each prefixed with `v1`. See Verifying signatures below.
`content-type`	`application/json`

Example delivery

POST /webhooks/slate HTTP/1.1
Host:            your-server.example.com
Content-Type:    application/json
svix-id:         msg_2uBSWQ3FJk9XrNqVeLDkTm3E
svix-timestamp:  1725897600
svix-signature:  v1,7q5h2Kz3mNpR1vLwXoYeAcBdFgHiJkMn4s6t8u0=

{
  "crid": "644333222",
  "downloadUrl": "https://slate.inc/download_url.pdf",
  "eventType": "DOCUMENT_READY",
  "fileRequestUUID": "e845435f-13a6-4c46-889a-ea6b27414494",
  "fileUUID": "d1ea8f8d-b07a-47f9-b02e-bbba960cf1e0",
  "matterUUID": "d2a64dba-a8bf-45be-ab91-424b4a99bd29",
  "wetInk": false
}

Responding to deliveries

Return any HTTP 2xx status within 30 seconds. Any non-2xx response or timeout triggers a retry.

Event types

Each webhook delivery carries an event type that identifies what happened. The payload’s eventType field holds it, so read eventType first to decide how to handle the rest of the body. Your endpoint only receives the event types it’s subscribed to. Every payload includes these fields:

Field	Type	Description
`eventType`	string	The event type, such as `DOCUMENT_READY` or `QCR_COMPLETED`. Always sent.
`crid`	string	The account reference number (CRID) assigned to this matter. Always sent.
`matterUUID`	string	UUID of the matter this event relates to. Use this to correlate the event with a record in your system. See each event type for when it’s sent.

`DOCUMENT_READY`

Fired when a signed or processed document becomes available on a matter.

{
  "crid": "644333222",
  "downloadUrl": "https://slate.inc/download_url.pdf",
  "eventType": "DOCUMENT_READY",
  "fileRequestUUID": "e845435f-13a6-4c46-889a-ea6b27414494",
  "fileUUID": "d1ea8f8d-b07a-47f9-b02e-bbba960cf1e0",
  "matterUUID": "d2a64dba-a8bf-45be-ab91-424b4a99bd29",
  "wetInk": false
}

Field	Type	Description
`matterUUID`	string	UUID of the matter the document belongs to. Always sent.
`downloadUrl`	string	The presigned download url of the pdf document: the signed document, or for a wet-ink workflow, the document described in Wet-ink documents. The embedded authentication in the url is valid for 60 minutes.
`fileRequestUUID`	string	Unique UUID of the process in which the document was signed.
`fileUUID`	string	Unique UUID of the document that `downloadUrl` points to. Can be used to distinguish documents.
`wetInk`	boolean	`true` when the document is signed in ink rather than electronically, otherwise `false`. Always sent.

Wet-ink documents

If a document is signed in ink rather than electronically, wetInk is true. Which document you receive depends on your workflow:

If QC comes before signing, your workflow completes when the document is marked for wet-ink signing. downloadUrl and fileUUID point to the prepared, unsigned document. You sign it in ink outside Slate.
If QC comes after signing, you upload the signed wet-ink scan to Slate for QC. downloadUrl and fileUUID point to the signed scan.

`QCR_COMPLETED`

Fired when a reviewer approves or rejects a quality control request. Use approved to tell the two outcomes apart. This event carries no document. A document request’s document is only created once QC approves it. When it’s ready, you receive it in a separate DOCUMENT_READY event with the same fileRequestUUID.

{
  "approved": false,
  "crid": "644333222",
  "eventType": "QCR_COMPLETED",
  "fileRequestUUID": "e845435f-13a6-4c46-889a-ea6b27414494",
  "matterUUID": "d2a64dba-a8bf-45be-ab91-424b4a99bd29",
  "occurredOn": "2026-11-02T19:07:03.547524349Z",
  "qcrUUID": "dd070715-6cf2-43f8-a107-001c5d43e029",
  "requestType": "QUALITY"
}

Field	Type	Description
`qcrUUID`	string	UUID of the QC request. Matches the `id` returned by `GET /v2/qc/requests/{qcrID}`. Always sent.
`approved`	boolean	`true` when the reviewer approved the QC request, `false` when they rejected it. Always sent.
`requestType`	string	`QUALITY` for a QC request raised against a document request, `REVIEW` for a standalone review. Always sent.
`occurredOn`	string	When the reviewer completed the QC request, as an RFC 3339 timestamp in UTC. Always sent.
`fileRequestUUID`	string	UUID of the document request the QC request was raised against. Matches `fileRequestUUID` on the `DOCUMENT_READY` event for the same document. Not sent for a standalone review.
`matterUUID`	string	UUID of the matter the document request belongs to. Not sent for a standalone review.

A QC decision can be undone and made again, so you may receive more than one QCR_COMPLETED for the same qcrUUID. Each has a different svix-id. Use occurredOn to find the latest decision. Additional event types will be added over time. Your Slate contact will notify you when new events become available for your integration. Slate follows an additive-only policy: existing fields will not be removed or renamed in a breaking way, and new fields may be added to any event type. Build your handler to ignore unknown fields and unknown event types.

Verifying signatures

Always verify the signature before processing a payload. This confirms the request came from Slate and hasn’t been tampered with.

How it works

Slate constructs a signed string from three components, then signs it with HMAC-SHA256 using your signing secret that will be shared at the time your endpoint is registered with Slate:

signed_content = "{svix-id}.{svix-timestamp}.{raw request body}"
signature      = Base64( HMAC-SHA256( signing_secret, signed_content ) )

The svix-signature header may contain multiple signatures (space-separated). A request is valid if any one of them matches — this supports secret rotation without downtime. Compare svix-timestamp to the current time and discard the request if the difference exceeds 5 minutes.

Using the Svix SDK (recommended)

Slate’s webhook delivery is powered by Svix, and Svix publishes official SDKs in Python, Node.js, Go, Java, Ruby, PHP, Rust, and more. The SDK handles signature verification, timestamp checking, and secret decoding in a single call.

from svix.webhooks import Webhook, WebhookVerificationError

SIGNING_SECRET = "whsec_..."  # provided by Slate

def handle_webhook(headers: dict, body: bytes):
    wh = Webhook(SIGNING_SECRET)
    try:
        payload = wh.verify(body, headers)
    except WebhookVerificationError:
        return 400  # invalid signature

    matter_uuid = payload["matterUUID"]
    crid = payload["crid"]
    # ... process the event
    return 200

Install: pip install svix

Manual verification — Python

import hmac, hashlib, base64, time

SIGNING_SECRET = "whsec_..."  # provided by Slate

def verify_signature(headers, body: str):
    msg_id    = headers["svix-id"]
    timestamp = headers["svix-timestamp"]
    sigs      = headers["svix-signature"]

    # Reject requests older than 5 minutes
    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError("Timestamp too old")

    # Decode the secret (strip the "whsec_" prefix, then base64-decode)
    secret_bytes = base64.b64decode(SIGNING_SECRET.removeprefix("whsec_"))

    signed_content = f"{msg_id}.{timestamp}.{body}"
    expected = base64.b64encode(
        hmac.new(secret_bytes, signed_content.encode(), hashlib.sha256).digest()
    ).decode()

    # svix-signature: "v1,<sig1> v1,<sig2> ..."
    received = [s.split(",", 1)[1] for s in sigs.split() if s.startswith("v1,")]
    if expected not in received:
        raise ValueError("Invalid signature")

Manual verification — Node.js

const crypto = require("crypto");

const SIGNING_SECRET = "whsec_..."; // provided by Slate

function verifySignature(headers, rawBody) {
  const msgId     = headers["svix-id"];
  const timestamp = headers["svix-timestamp"];
  const sigs      = headers["svix-signature"];

  // Reject stale timestamps (>5 min)
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    throw new Error("Timestamp too old");
  }

  // Decode the secret (strip "whsec_" prefix, then base64-decode)
  const secretBytes = Buffer.from(
    SIGNING_SECRET.replace(/^whsec_/, ""), "base64"
  );

  const signedContent = `${msgId}.${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac("sha256", secretBytes)
    .update(signedContent)
    .digest("base64");

  const received = sigs
    .split(" ")
    .filter(s => s.startsWith("v1,"))
    .map(s => s.slice(3));

  if (!received.includes(expected)) {
    throw new Error("Invalid signature");
  }
}

Retries and delivery

If your endpoint doesn’t return a 2xx within 30 seconds, Slate retries with exponential backoff:

Attempt	Delay
2	5 seconds
3	1 minute
4	5 minutes
5	30 minutes
6	2 hours
7	5 hours
8	10 hours
9	24 hours

After 9 attempts the message is marked failed. Contact your Slate integration contact if you need a missed event replayed.

Idempotency

Because a delivery may be attempted more than once, your handler should be idempotent. Processing the same event twice should produce the same result as processing it once. Use the svix-id header as a stable unique key to deduplicate incoming events.

Ordering

Events are delivered in order on a best-effort basis. Retries and network conditions can cause reordering, so design your handler to tolerate out-of-order events if strict ordering matters to your use case.

Get Started

Core Concepts

Guides

Getting started

Receiving events

Request headers

Example delivery

Responding to deliveries

Event types

`DOCUMENT_READY`

Wet-ink documents

`QCR_COMPLETED`

Verifying signatures

How it works

Using the Svix SDK (recommended)

Manual verification — Python

Manual verification — Node.js

Retries and delivery

Idempotency

Ordering

​Getting started

​Receiving events

​Request headers

​Example delivery

​Responding to deliveries

​Event types

​DOCUMENT_READY

​Wet-ink documents

​QCR_COMPLETED

​Verifying signatures

​How it works

​Using the Svix SDK (recommended)

​Manual verification — Python

​Manual verification — Node.js

​Retries and delivery

​Idempotency

​Ordering

Getting started

Receiving events

Request headers

Example delivery

Responding to deliveries

Event types

`DOCUMENT_READY`

Wet-ink documents

`QCR_COMPLETED`

Verifying signatures

How it works

Using the Svix SDK (recommended)

Manual verification — Python

Manual verification — Node.js

Retries and delivery

Idempotency

Ordering