Webhooks

Webhooks push signed JSON events to your endpoints as things happen — no polling. Manage endpoints via the API (/v1/webhook-endpoints, scope webhooks:manage) or in the Customer Portal under Account Settings → Webhooks, where you can also inspect recent deliveries, retry failures, and send test events.

Events

Subscriptions accept exact names, * (everything), or prefix wildcards like order.*.

Event	Fires when
`quote.requested`	A quote request was submitted
`quote.ready`	The quote was priced and awaits your approval
`quote.approved`	The quote was approved (includes an order summary)
`quote.cancelled`	The quote was cancelled
`order.created`	An order was created from an approved quote
`order.in_progress`	Work on the order started
`order.ready_for_review`	Deliverables are ready for your review
`order.completed`	The order is complete
`order.cancelled`	The order was cancelled
`order.refunded`	The order was refunded
`file.ready`	A URL-ingested file finished processing
`file.failed`	A URL-ingested file could not be processed
`document.approved`	A deliverable document was approved
`ping`	Test event (sent from the portal or on request)

Payload

Every delivery is a POST with a Stripe-style envelope. data.object matches the shape the API returns for the same resource:

{
  "id": "evt_01JZX...",
  "type": "order.completed",
  "api_version": "v1",
  "created": "2026-07-08T12:00:00+00:00",
  "data": {
    "object": { "id": "ordr_...", "status": "completed", "...": "..." }
  }
}

Headers on every delivery:

Header	Contents
`X-Fortis-Signature`	`t=<unix timestamp>,v1=<signature>` (see below)
`X-Fortis-Event`	The event type, e.g. `order.completed`
`X-Fortis-Event-Id`	The `evt_...` id shared by all endpoints receiving this occurrence
`X-Fortis-Delivery`	Unique delivery id — use as an idempotency key
`X-Fortis-Webhook-Id`	The endpoint receiving the delivery

Verifying signatures

Each endpoint has a whsec_... signing secret (returned once on creation, viewable in the portal). The v1 signature is an HMAC-SHA256 of {timestamp}.{raw request body} using that secret:

function verifyFortisSignature(string $payload, string $header, string $secret): bool
{
    if (! preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m)) {
        return false;
    }

    [, $timestamp, $signature] = $m;

    if (abs(time() - (int) $timestamp) > 300) {
        return false; // replay protection: reject events older than 5 minutes
    }

    $expected = hash_hmac('sha256', $timestamp.'.'.$payload, $secret);

    return hash_equals($expected, $signature);
}

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyFortisSignature(payload, header, secret) {
  const match = header?.match(/^t=(\d+),v1=([0-9a-f]{64})$/);
  if (!match) return false;

  const [, timestamp, signature] = match;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${payload}`)
    .digest("hex");

  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Compute the HMAC over the raw request body exactly as received — parsing and re-serializing the JSON will change the bytes and break verification.

Delivery, retries, and failures

Respond with any 2xx within 10 seconds. Do heavy processing async.
Failed deliveries are retried up to 6 times with increasing backoff (1 minute → 8 hours).
After 20 consecutive failed deliveries, the endpoint is automatically disabled. Re-enable it in the portal or via PUT /v1/webhook-endpoints/{id} with { "disabled": false }.
Delivery order is not guaranteed. Use the envelope’s created timestamp, and fetch the resource from the API when you need its latest state.
Deliveries may occasionally repeat — deduplicate on the X-Fortis-Delivery header.

Endpoint requirements

HTTPS URLs pointing at publicly reachable hosts.
Endpoints are managed per app: an API key can only manage its own app’s endpoints.

Getting Started

Guides

Events

Payload

Verifying signatures

Delivery, retries, and failures

Endpoint requirements

​Events

​Payload

​Verifying signatures

​Delivery, retries, and failures

​Endpoint requirements

Events

Payload

Verifying signatures

Delivery, retries, and failures

Endpoint requirements