> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quiva.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HelloSign callback

> Webhook endpoint for HelloSign signature events. **Called by the HelloSign platform, not by internal services** — configure it as the callback URL in the HelloSign app settings. The event arrives as a multipart form field named `json`.

Handled event types:
- `signature_request_signed` — one signatory signed; their status on the document becomes `SIGNED` (matched by signer name + email).
- `signature_request_all_signed` — all signatories signed; the fully executed PDF is downloaded from HelloSign and written back over the document's output location in storage.
- `signature_request_invalid` — the request failed; affected signatories are marked `FAILED` with the `error` field populated.

Unrecognised event types are silently ignored. Each event's `event_hash` is verified as HMAC-SHA256(`event_time` + `event_type`) using the account's HelloSign API key; events with a hash mismatch are discarded. The endpoint **always** responds `200 Hello API Event Received` regardless of processing outcome.



## OpenAPI

````yaml /api-reference/endpoint/documents/openapi.json post /file-generator/webhooks/hellosign/{account}
openapi: 3.1.0
info:
  title: Documents API
  description: >-
    Document templates, generated documents, e-signature requests, and checkbox
    approvals. Template and document routes are served under `/file-generator`,
    approval routes under `/workspaces/approvals`.
  version: 1.2.0
servers:
  - url: https://api.quiva.ai
    description: Production API server
security:
  - bearerAuth: []
  - apiKeyAuth: []
tags:
  - name: Templates
    description: >-
      Template lifecycle — create, read, publish, validate, trigger, and delete
      document templates. Templates follow a **draft → published** model: writes
      (`POST`, `PATCH`) always target the draft version, and `POST
      /templates/{key}/publish` promotes the draft. Document generation only
      ever uses the published version, so drafts can be edited safely without
      affecting production output. A template's `source` is a DOCX file
      containing angular-expression tags rendered at trigger time.
  - name: Documents
    description: >-
      Document lifecycle — read, update, and delete generated documents. A
      document record is created immediately when a template is triggered and is
      updated asynchronously: first with the generated `output.key` (an `obj://`
      or `kv://` storage URI) or `errors`, then with `signatures` progress as
      signatories sign.
  - name: Signatures
    description: >-
      E-signature workflows powered by HelloSign (Dropbox Sign). Signature
      requests are created automatically when a triggered template defines
      `signatories`. Each signatory tracks a status lifecycle of `DRAFT → SENT →
      SIGNED`, with `EXPIRED` (validity window elapsed) and `FAILED`
      (delivery/signing error) as terminal failure states. Embedded signing URLs
      can be generated for signatures created in embedded mode.
  - name: Approvals
    description: Checkbox approval of a workspace file, recorded as e-signature evidence.
  - name: Generation
  - name: Template Source
paths:
  /file-generator/webhooks/hellosign/{account}:
    post:
      tags:
        - Signatures
      summary: HelloSign callback
      description: >-
        Webhook endpoint for HelloSign signature events. **Called by the
        HelloSign platform, not by internal services** — configure it as the
        callback URL in the HelloSign app settings. The event arrives as a
        multipart form field named `json`.


        Handled event types:

        - `signature_request_signed` — one signatory signed; their status on the
        document becomes `SIGNED` (matched by signer name + email).

        - `signature_request_all_signed` — all signatories signed; the fully
        executed PDF is downloaded from HelloSign and written back over the
        document's output location in storage.

        - `signature_request_invalid` — the request failed; affected signatories
        are marked `FAILED` with the `error` field populated.


        Unrecognised event types are silently ignored. Each event's `event_hash`
        is verified as HMAC-SHA256(`event_time` + `event_type`) using the
        account's HelloSign API key; events with a hash mismatch are discarded.
        The endpoint **always** responds `200 Hello API Event Received`
        regardless of processing outcome.
      operationId: hellosignCallback
      parameters:
        - name: account
          in: path
          required: true
          description: Account id the webhook event is routed to.
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                json:
                  type: string
                  description: >-
                    JSON-encoded HelloSign event payload. Contains `event`
                    (type, time, HMAC hash) and `signature_request` (signatures
                    with status, plus `metadata.subject` / `metadata.key` that
                    route the event back to the originating document).
      responses:
        '200':
          description: >-
            Event received. The body is the plain string `Hello API Event
            Received`. The handler responds `200` even when event processing
            fails (hash mismatch, unknown account, lookup errors) so that
            HelloSign does not retry — processing errors are logged server-side
            only.
          content:
            application/json:
              schema:
                type: string
                example: Hello API Event Received
              example: Hello API Event Received
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.