pdfs-build Webhooks API

openapi: 3.2.0
info:
  title: pdfs.build Webhooks API
  version: '2.0'
  summary: Render PDFs from templates, manage templates, webhooks, embedded editor sessions and delegated agent access.
  description: 'All requests are authenticated with an organization-scoped API key (`prs_...`) sent as a Bearer token. Create keys under **Settings → API Keys** in the dashboard or with the MCP `create_api_key` tool. Keys are shown once.


    The organization in every `/v2` URL must match the key''s organization, otherwise the request fails with `403 organization_scope_mismatch`.


    **Errors** are JSON with a top-level `error` string — a machine-readable code for most failures, a phrase for a few legacy ones — usually alongside a human-readable `message`. Data validation and template compilation failures carry `details` / `diagnostics` instead of a `message`.


    **Versions.** `/v2` addresses templates by an external id you control. The legacy `/v1` routes identify templates by their generated internal id and remain supported for existing integrations.


    **Timestamps.** Objects served by the render service (templates, render jobs, logs, webhook endpoints) carry UTC timestamps in ISO 8601 form without a timezone suffix, e.g. `2026-08-30T12:00:00.123456`. Embedded-editor sessions and delegated access return RFC 3339 with a trailing `Z`.


    The narrative guide — authentication, webhook signatures, the MCP server, migrating from v1 — lives at https://pdfs.build/docs/ (Markdown mirror: https://pdfs.build/docs.md).'
  contact:
    name: pdfs.build
    url: https://pdfs.build
    email: hello@pdfs.build
  termsOfService: https://pdfs.build/terms/
  license:
    name: Proprietary
    url: https://pdfs.build/terms/
servers:
- url: https://api.pdfs.build
  description: Production
security:
- apiKey: []
tags:
- name: Webhooks
  description: Outbound endpoints notified when API renders complete or fail. Creating, rotating and testing require a paid plan; listing, updating, deleting and reading deliveries do not.
paths:
  /v2/organizations/{organizationId}/webhooks:
    parameters:
    - $ref: '#/components/parameters/organizationId'
    get:
      tags:
      - Webhooks
      summary: List webhook endpoints
      operationId: listWebhookEndpoints
      description: Secrets are never returned.
      responses:
        '200':
          description: Endpoints, newest first.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookEndpoint'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/OrganizationScopeMismatch'
    post:
      tags:
      - Webhooks
      summary: Create webhook endpoint
      operationId: createWebhookEndpoint
      description: Registers a public http(s) URL. Non-global destinations (loopback, private, link-local, CGNAT and other reserved ranges, IPv4 and IPv6) are rejected at registration and re-validated before every delivery. The signing secret (`whsec_...`) is returned exactly once. Requires a paid plan.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '201':
          description: The endpoint and its secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointWithSecret'
        '400':
          $ref: '#/components/responses/WebhookUrlRejected'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WebhookPlanGated'
  /v2/organizations/{organizationId}/webhooks/{endpointId}:
    parameters:
    - $ref: '#/components/parameters/organizationId'
    - $ref: '#/components/parameters/endpointId'
    patch:
      tags:
      - Webhooks
      summary: Update webhook endpoint
      operationId: updateWebhookEndpoint
      description: Change the URL, description or enabled state. Disabling an endpoint stops future deliveries; deliveries already queued are dropped. Not plan-gated.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookRequest'
      responses:
        '200':
          description: The updated endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          $ref: '#/components/responses/WebhookUrlRejected'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/OrganizationScopeMismatch'
        '404':
          $ref: '#/components/responses/WebhookNotFound'
    delete:
      tags:
      - Webhooks
      summary: Delete webhook endpoint
      operationId: deleteWebhookEndpoint
      description: Soft delete. Not plan-gated.
      responses:
        '200':
          $ref: '#/components/responses/Ok'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/OrganizationScopeMismatch'
        '404':
          $ref: '#/components/responses/WebhookNotFound'
  /v2/organizations/{organizationId}/webhooks/{endpointId}/rotate-secret:
    parameters:
    - $ref: '#/components/parameters/organizationId'
    - $ref: '#/components/parameters/endpointId'
    post:
      tags:
      - Webhooks
      summary: Rotate signing secret
      operationId: rotateWebhookSecret
      description: Replaces the endpoint's secret. The new secret is returned exactly once. Requires a paid plan.
      responses:
        '200':
          description: The endpoint and its new secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointWithSecret'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WebhookPlanGated'
        '404':
          $ref: '#/components/responses/WebhookNotFound'
  /v2/organizations/{organizationId}/webhooks/{endpointId}/test:
    parameters:
    - $ref: '#/components/parameters/organizationId'
    - $ref: '#/components/parameters/endpointId'
    post:
      tags:
      - Webhooks
      summary: Send test event
      operationId: testWebhookEndpoint
      description: Enqueues a `webhook.test` event to this endpoint. The body is optional; a missing or malformed body falls back to the default message. Requires a paid plan.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookTestRequest'
      responses:
        '201':
          description: The queued delivery.
          content:
            application/json:
              schema:
                type: object
                required:
                - delivery
                properties:
                  delivery:
                    $ref: '#/components/schemas/WebhookDelivery'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WebhookPlanGated'
        '404':
          $ref: '#/components/responses/WebhookNotFound'
  /v2/organizations/{organizationId}/webhooks/{endpointId}/deliveries:
    parameters:
    - $ref: '#/components/parameters/organizationId'
    - $ref: '#/components/parameters/endpointId'
    get:
      tags:
      - Webhooks
      summary: List recent deliveries
      operationId: listWebhookDeliveries
      description: The 50 most recent deliveries to this endpoint, for debugging. Not plan-gated.
      responses:
        '200':
          description: Deliveries, newest first.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookDelivery'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/OrganizationScopeMismatch'
        '404':
          $ref: '#/components/responses/WebhookNotFound'
webhooks:
  render.completed:
    post:
      tags:
      - Webhooks
      summary: render.completed
      operationId: renderCompletedEvent
      description: 'An API render (sync or async) finished successfully. Delivered to every enabled endpoint, or to the `webhookIds` named on the render. Signed with the Standard Webhooks scheme (`webhook-id`, `webhook-timestamp`, `webhook-signature: v1,` over `"{id}.{timestamp}.{body}"`, keyed by the endpoint secret). Respond with any 2xx within 5 seconds; otherwise the delivery is retried up to 10 times with capped exponential backoff.'
      parameters:
      - $ref: '#/components/parameters/webhookId'
      - $ref: '#/components/parameters/webhookTimestamp'
      - $ref: '#/components/parameters/webhookSignature'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenderEvent'
            example:
              id: evt_9f2cQxT0Rq2m8n5WkYb3Lw
              type: render.completed
              createdAt: '2026-08-30T12:00:00.000Z'
              data:
                renderId: d4e5f6a7-1b2c-4d3e-9f80-123456789abc
                jobId: job_7a1b9c2d
                organizationId: org_abc
                templateExternalId: invoice-primary
                status: success
                durationMs: 123
                downloadUrl: https://api.pdfs.build/v2/organizations/org_abc/renders/job_7a1b9c2d/pdf
      responses:
        2XX:
          description: Acknowledged.
  render.failed:
    post:
      tags:
      - Webhooks
      summary: render.failed
      operationId: renderFailedEvent
      description: 'An API render failed: compilation error, storage failure, or an async job that exhausted its retries. Same delivery and signature rules as `render.completed`.'
      parameters:
      - $ref: '#/components/parameters/webhookId'
      - $ref: '#/components/parameters/webhookTimestamp'
      - $ref: '#/components/parameters/webhookSignature'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenderEvent'
            example:
              id: evt_2bN8xQ1kTfWc7yLp0aRdEg
              type: render.failed
              createdAt: '2026-08-30T12:00:00.000Z'
              data:
                renderId: d4e5f6a7-1b2c-4d3e-9f80-123456789abc
                organizationId: org_abc
                templateExternalId: invoice-primary
                status: error
                errorMessage: 'Compilation failed: unknown variable: due_date'
      responses:
        2XX:
          description: Acknowledged.
  batch.completed:
    post:
      tags:
      - Webhooks
      summary: batch.completed
      operationId: batchCompletedEvent
      description: Every item of a render batch has succeeded or failed. Sent once per batch. Fetch `GET /v2/organizations/{organizationId}/batches/{batchId}` for per-item results and download links. Same delivery and signature rules as `render.completed`.
      parameters:
      - $ref: '#/components/parameters/webhookId'
      - $ref: '#/components/parameters/webhookTimestamp'
      - $ref: '#/components/parameters/webhookSignature'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchEvent'
            example:
              id: evt_4kR7mPq2VsXc9zNb1hTdYw
              type: batch.completed
              createdAt: '2026-09-23T12:00:00.000Z'
              data:
                batchId: batch_3f6a0c1e
                organizationId: org_abc
                templateExternalId: invoice-primary
                total: 2
                succeeded: 2
                failed: 0
      responses:
        2XX:
          description: Acknowledged.
  webhook.test:
    post:
      tags:
      - Webhooks
      summary: webhook.test
      operationId: webhookTestEvent
      description: Sent by the dashboard or the test endpoint.
      parameters:
      - $ref: '#/components/parameters/webhookId'
      - $ref: '#/components/parameters/webhookTimestamp'
      - $ref: '#/components/parameters/webhookSignature'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookTestEvent'
      responses:
        2XX:
          description: Acknowledged.
components:
  schemas:
    Timestamp:
      type: string
      description: UTC, ISO 8601 without a timezone suffix.
      example: '2026-08-30T12:00:00.123456'
    UpdateWebhookRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
        description:
          type:
          - string
          - 'null'
          description: '`null` clears the description; omit to leave it unchanged.'
        enabled:
          type: boolean
    WebhookDelivery:
      type: object
      required:
      - id
      - endpointId
      - eventType
      - status
      - attempts
      - createdAt
      properties:
        id:
          type: string
          description: Event id (`evt_...`), also sent as the `webhook-id` header.
        endpointId:
          type: string
        eventType:
          type: string
          enum:
          - render.completed
          - render.failed
          - webhook.test
        status:
          type: string
          enum:
          - pending
          - processing
          - delivered
          - failed
        attempts:
          type: integer
        lastResponseStatus:
          type:
          - integer
          - 'null'
        lastError:
          type:
          - string
          - 'null'
        createdAt:
          $ref: '#/components/schemas/Timestamp'
        deliveredAt:
          oneOf:
          - $ref: '#/components/schemas/Timestamp'
          - type: 'null'
    WebhookTestEvent:
      type: object
      required:
      - id
      - type
      - createdAt
      - data
      properties:
        id:
          type: string
        type:
          type: string
          const: webhook.test
        createdAt:
          type: string
          format: date-time
        data:
          type: object
          required:
          - message
          - organizationId
          - endpointId
          properties:
            message:
              type: string
            organizationId:
              type: string
            endpointId:
              type: string
    CreateWebhookRequest:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          description: Public http(s) destination.
        description:
          type: string
        enabled:
          type: boolean
          default: true
    RenderEvent:
      type: object
      required:
      - id
      - type
      - createdAt
      - data
      properties:
        id:
          type: string
          description: Unique per delivery (`evt_...`).
        type:
          type: string
          enum:
          - render.completed
          - render.failed
        createdAt:
          type: string
          format: date-time
        data:
          type: object
          required:
          - renderId
          - organizationId
          - status
          properties:
            renderId:
              type: string
              description: The render log id.
            jobId:
              type: string
              description: Async renders only.
            organizationId:
              type: string
            templateExternalId:
              type: string
            status:
              type: string
              enum:
              - success
              - error
            durationMs:
              type: integer
            errorMessage:
              type: string
              description: '`render.failed` only.'
            downloadUrl:
              type: string
              format: uri
              description: Successful async renders only. Requires the API key.
    WebhookEndpoint:
      type: object
      required:
      - id
      - organizationId
      - url
      - enabled
      - description
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
          example: whe_5xg6Kq0PSTeK1bXf3eDR3w
        organizationId:
          type: string
        url:
          type: string
          format: uri
        enabled:
          type: boolean
        description:
          type:
          - string
          - 'null'
        createdAt:
          $ref: '#/components/schemas/Timestamp'
        updatedAt:
          $ref: '#/components/schemas/Timestamp'
    BatchEvent:
      type: object
      required:
      - id
      - type
      - createdAt
      - data
      properties:
        id:
          type: string
          description: Unique per delivery (`evt_...`).
        type:
          type: string
          const: batch.completed
        createdAt:
          type: string
          format: date-time
        data:
          type: object
          required:
          - batchId
          - organizationId
          - total
          - succeeded
          - failed
          properties:
            batchId:
              type: string
            organizationId:
              type: string
            templateExternalId:
              type: string
            total:
              type: integer
            succeeded:
              type: integer
            failed:
              type: integer
    WebhookTestRequest:
      type: object
      properties:
        message:
          type: string
          description: Carried in `data.message` of the test event.
    Ok:
      type: object
      required:
      - ok
      properties:
        ok:
          type: boolean
          const: true
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Machine-readable code (e.g. `draft_not_renderable`) or, for a few legacy failures, a short phrase.
        message:
          type: string
          description: Human-readable detail. Present on most coded errors.
      example:
        error: draft_not_renderable
        message: Only published templates can be rendered via the API. Publish this template first.
    WebhookEndpointWithSecret:
      type: object
      required:
      - endpoint
      - secret
      properties:
        endpoint:
          $ref: '#/components/schemas/WebhookEndpoint'
        secret:
          type: string
          description: Standard Webhooks signing secret (`whsec_` + base64). Shown once; store it now.
          example: whsec_MfKjnR7bCq4Xy1UvZ0aW3sTdE9gHpLqI5oN2kBjA8xY=
  responses:
    WebhookUrlRejected:
      description: '`invalid_url` (not a well-formed http(s) URL) or `url_not_allowed` (resolves to a non-public address).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    OrganizationScopeMismatch:
      description: The organization in the URL does not match the API key's organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: organization_scope_mismatch
            message: The organization in the URL does not match the API key organization
    Unauthorized:
      description: Missing, invalid or expired API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
    WebhookNotFound:
      description: '`not_found` — no such endpoint in this organization.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: not_found
            message: Webhook endpoint not found
    WebhookPlanGated:
      description: '`plan_gated` (webhooks need a paid plan) or `organization_scope_mismatch`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Ok:
      description: Done.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Ok'
  parameters:
    webhookTimestamp:
      name: webhook-timestamp
      in: header
      required: true
      schema:
        type: string
      description: Unix seconds.
    endpointId:
      name: endpointId
      in: path
      required: true
      schema:
        type: string
      description: Webhook endpoint id (`whe_...`).
    webhookId:
      name: webhook-id
      in: header
      required: true
      schema:
        type: string
      description: The event id (`evt_...`). Unique per delivery; use it for idempotency.
    organizationId:
      name: organizationId
      in: path
      required: true
      schema:
        type: string
      description: Your organization id. Must match the API key's organization.
      example: org_abc
    webhookSignature:
      name: webhook-signature
      in: header
      required: true
      schema:
        type: string
      description: '`v1,<base64 HMAC-SHA256>` per the Standard Webhooks spec.'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: prs_...
      description: Organization-scoped API key, created under Settings → API Keys or with the MCP `create_api_key` tool.
externalDocs:
  description: 'API guide: authentication, errors, webhooks, MCP, migrating from v1'
  url: https://pdfs.build/docs/