Formify Webhooks API

openapi: 3.2.0
info:
  title: Formify Webhooks API
  description: '## Overview


    The Formify API lets you send documents for electronic signature, prepare drafts, track signing status, and retrieve signed documents. It is designed for integrating signing workflows into your application.


    ### Getting Access


    OAuth 2.0 is the recommended way to access the API. Before you can use the API, you need an OAuth 2.0 client. Formify creates this for you based on information about your company, contacts, and redirect URIs. See the **Getting Access** guide for setup instructions.


    Once your OAuth client has been created, you can use the OAuth 2.0 Authorization Code flow to obtain access tokens for API requests.


    For MCP clients and third-party platforms that cannot complete OAuth/PKCE and only accept a pasted token, a Formify API key can be exchanged for a short-lived access token with `POST /auth/token`. This is a compatibility option; use OAuth where the client supports it.


    ### Authentication


    Protected API requests use a Bearer access token. The recommended flow is OAuth 2.0: your application redirects the user to Formify for authorization, receives an authorization code, and exchanges it for an access token. See the OAuth 2.0 section for the complete flow.


    ### Environments


    **API base URL**: `https://docs-api.formify.eu/v1`

    All document operations, file uploads, and token exchange endpoints (OAuth and API key fallback) happen here.


    **Authorization Server**: `https://app.formify.eu`

    This is where users authorize your application and approve access (the OAuth consent).


    ### Rate Limiting


    The API uses token-based rate limiting to ensure fair usage:


    - **Headers**: Every response includes rate limit headers:

    - `X-RateLimit-Limit`: Maximum requests allowed

    - `X-RateLimit-Remaining`: Requests remaining in current window

    - `X-RateLimit-Reset`: The number of seconds until the rate limit resets


    - **Not every request costs the same.** Endpoints that build or copy a document consume several tokens

    rather than one, because they render a PDF and make multiple calls to the document service. Creating,

    editing or duplicating a document or a public link is the most expensive; creating or editing a template

    costs less; deleting and duplicating a draft less again. Plain reads cost one.


    If you exceed the limit, the API returns `429 Too Many Requests`. Wait until the reset time before making additional requests.


    ---


    ## Quick Start: Send a PDF for Signing


    Once you have a valid `access_token`, you can send your first document for signing in three steps:


    ### 1. Upload a PDF

    Upload a PDF file using the Upload File endpoint:


    ```bash

    POST /files

    Content-Type: multipart/form-data

    ```


    You will receive a `fileId` in the response.


    ### 2. Create a Signature Request

    Send the document for signing using the Create Document endpoint:


    ```bash

    POST /docs

    {

    "fileId": "your-file-id",

    "signeeDetails": [

    {

    "fullName": "John Doe",

    "emailAddress": "john@example.com",

    "signaturePlacement": "new_page"

    }

    ]

    }

    ```


    The response returns a documentId. The signee then receives an email with a link to sign the document.


    ### 3. Get Notified and Download

    Register a webhook to receive a notification when the document is signed:


    ```bash

    POST /webhooks

    {

    "webhookUrl": "https://your-app.com/webhook",

    "eventTypes": ["document.completed"]

    }

    ```


    Then download the signed PDF using Get Signed Document File:


    ```bash

    GET /docs/{documentId}/signed-file

    ```


    For more detailed walkthroughs, see the **Integration Flows** guide.


    ---


    ### Help


    - **Getting Access** - How to set up OAuth 2.0 credentials

    - **Integration Flows** - Step-by-step guides for common integration scenarios

    - **PDF Form Attributes** - How to add `tink-*` attributes to PDF form field names

    - **MCP Server** - Connect AI assistants with OAuth or an API key fallback for token-only clients

    - **Production Checklist** - Essential steps before going live


    ### Links


    - Formify API Changelog - Track API updates and changes

    - Formify App - Register OAuth applications and manage settings


    ---'
  contact:
    email: api@formify.eu
  version: 1.5.2
  termsOfService: https://formify.eu/privacy/terms
servers:
- url: https://docs-api.formify.eu/v1
  description: Main API server for all document related endpoints and token exchange.
security:
- OAuth2: []
tags:
- name: Webhooks
  description: Webhooks operations
paths:
  /webhooks:
    post:
      tags:
      - Webhooks
      summary: Register a new webhook
      description: 'Register a new webhook to receive event notifications. ### About Webhooks

        Webhooks allow Formify to communicate with your system using callbacks triggered by specified Formify events. Webhooks provide real-time data updates, enabling you to integrate Formify events directly into your workflows. #### What’s the use for webhooks? With webhooks, you can be notified of specific events to automate workflows such as sending documents for signature or tracking their status in real-time. #### How do I set up webhooks? When you create a webhook, specify the events you''d like to subscribe to. To reduce unnecessary requests to your server, only subscribe to the events you plan to handle. ### Entity Types

        Formify uses entity types to filter webhook events based on the scope of data you want to receive. The entity type defines which object changes in Formify trigger your webhook. | Entity Type | Description | Example |

        |-------------------|-------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|

        | **Document** | Subscribe to events involving a specific document. | A document is sent for signature, signed, or completed (sealed). Each change triggers your webhook. |


        ### Supported Events

        - `document.created`: A document has been created/sent for signature. - `document.opened`: A document has been opened. - `document.signed`: A document has been signed by a signee. - `document.completed`: A document process has been signed by all parties and is sealed. - `document.revoked`: A document has been revoked. - `document.deleted`: A document has been deleted. ### Notes

        - Other entity types (e.g., `settings.x`) are not yet supported. - Do not assume ordering: Events may arrive late, more than once, or out of order


        ### Webhook Request Payload

        - See the `DocumentWebhookEvent` schema for the structure of the Document entity type payload. #### Example for General Events (`document.created`, `document.opened`, etc.)

        ```json

        {

        "event": {

        "eventId": "123e4567-e89b-12d3-a456-426614174000",

        "type": "document.created",

        "date": "2024-10-25T14:23:55Z",

        "data": {

        "documentId": "789e4567-e89b-12d3-a456-426614174111",

        "accountId": "456e4567-e89b-12d3-a456-426614174222",

        "userId": "123e4567-e89b-12d3-a456-426614174333"

        }

        }

        }

        ```


        - **eventId**: The unique identifier for the event instance. - **type**: The type of the event that triggered the webhook. - **date**: The date and time the event was triggered in ISO 8601 format. - **data**: Contains the `documentId`, `userId` and `accountId` relevant to the event. #### Example for `document.signed` Event

        ```json

        {

        "event": {

        "eventId": "123e4567-e89b-12d3-a456-426614174000",

        "type": "document.signed",

        "date": "2024-10-25T14:23:55Z",

        "data": {

        "documentId": "789e4567-e89b-12d3-a456-426614174111",

        "accountId": "456e4567-e89b-12d3-a456-426614174222",

        "userId": "123e4567-e89b-12d3-a456-426614174333",

        "signeeId": "789e4567-e89b-12d3-a456-426614174555"

        }

        }

        }

        ```


        ### Notes

        - All event payloads include `eventId`, `type`, `date`, and a `data` object with event-specific details. - The data object may differ between events and the `signeeId` field is only included for the `document.signed` event. ### Expected Response for Webhooks

        To acknowledge receipt of the webhook, your server should respond with an HTTP status code in the 2xx range. No specific content is required in the response body; a `200 OK` status alone will indicate successful processing. #### Example Response

        ```http

        HTTP/1.1 200 OK

        Content-Type: application/json

        ```


        ### Retry Attempts

        Formify will attempt to deliver webhook events up to 5 times if the initial attempt fails. The retry intervals* are as follows:

        - First retry: "immediately"

        - Second retry: after ~5 minutes

        - Third retry: after ~30 minutes

        - Fourth retry: after ~2 hours

        - Fifth retry: after ~24 hours


        *The intervals are not exact and may vary slightly.'
      operationId: registerWebhook
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                webhookUrl:
                  type: string
                  format: uri
                  description: The URL where webhook events will be sent.
                name:
                  type: string
                  description: The name/alias of the webhook for you to identify it.
                eventTypes:
                  type: array
                  items:
                    type: string
                    enum:
                    - document.created
                    - document.opened
                    - document.signed
                    - document.completed
                    - document.revoked
                    - document.deleted
                  description: A list of event types that the webhook will be subscribed to.
        required: true
      responses:
        '201':
          description: Webhook registered successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhookId:
                    type: string
                    format: uuid
                    description: The unique identifier of the registered webhook.
                  eventTypes:
                    type: array
                    items:
                      type: string
                      enum:
                      - document.created
                      - document.opened
                      - document.signed
                      - document.completed
                      - document.revoked
                      - document.deleted
                    description: A list of event types the webhook is subscribed to.
                  signingSecret:
                    type: string
                    description: 'HMAC signing secret for this webhook. Store this securely — it is used to verify webhook payloads.

                      Prefixed with `whsec_`.'
                    example: whsec_dGhpcyBpcyBhIHNhbXBsZSBzZWNyZXQ=
              example:
                webhookId: 123e4567-e89b-12d3-a456-426614174000
                eventTypes:
                - document.opened
                - document.signed
                signingSecret: whsec_dGhpcyBpcyBhIHNhbXBsZSBzZWNyZXQ=
        '401':
          description: Unauthorized - Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
      x-codeSamples:
      - lang: curl
        source: "curl -X POST \"https://docs-api.formify.eu/v1/webhooks\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n  \"webhookUrl\": \"string\",\n  \"name\": \"string\",\n  \"eventTypes\": [\n    \"document.created\"\n  ]\n}'"
      - lang: JavaScript
        source: "const response = await fetch(\"https://docs-api.formify.eu/v1/webhooks\", {\n  method: \"POST\",\n  headers: {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"webhookUrl\": \"string\",\n    \"name\": \"string\",\n    \"eventTypes\": [\n        \"document.created\"\n    ]\n})\n});\n\nconst data = await response.json();\nconsole.log(data);"
      - lang: Python
        source: "import requests\n\nurl = \"https://docs-api.formify.eu/v1/webhooks\"\nheaders = {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n}\npayload = {\n    \"webhookUrl\": \"string\",\n    \"name\": \"string\",\n    \"eventTypes\": [\n        \"document.created\"\n    ]\n}\n\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
    get:
      tags:
      - Webhooks
      summary: Get all registered webhooks
      description: This endpoint retrieves all registered webhooks.
      operationId: getAllWebhooks
      parameters:
      - in: query
        name: errorLanguage
        schema:
          type: string
          enum:
          - en
          - sv
          - es
        description: Language for the error message
      responses:
        '200':
          description: List of registered webhooks fetched successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    webhookId:
                      type: string
                      format: uuid
                      description: The unique identifier of the webhook.
                    webhookUrl:
                      type: string
                      format: uri
                      description: The URL where webhook events are sent.
                    name:
                      type: string
                      description: The name of the webhook.
                    eventTypes:
                      type: array
                      items:
                        type: string
                        description: The event types that the webhook is subscribed to.
                    signingSecret:
                      type: string
                      description: HMAC signing secret for this webhook.
                      example: whsec_dGhpcyBpcyBhIHNhbXBsZSBzZWNyZXQ=
        '401':
          description: Unauthorized - Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
      x-codeSamples:
      - lang: curl
        source: "curl -X GET \"https://docs-api.formify.eu/v1/webhooks\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\""
      - lang: JavaScript
        source: "const response = await fetch(\"https://docs-api.formify.eu/v1/webhooks\", {\n  method: \"GET\",\n  headers: {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n  }\n});\n\nconst data = await response.json();\nconsole.log(data);"
      - lang: Python
        source: "import requests\n\nurl = \"https://docs-api.formify.eu/v1/webhooks\"\nheaders = {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n}\n\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
  /webhooks/{webhookId}:
    get:
      tags:
      - Webhooks
      summary: Get a specific webhook
      description: This endpoint retrieves a specific webhook by its unique identifier.
      operationId: getWebhookById
      parameters:
      - in: path
        name: webhookId
        required: true
        schema:
          type: string
          format: uuid
        description: The unique identifier of the webhook to retrieve.
      responses:
        '200':
          description: Webhook retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhookId:
                    type: string
                    format: uuid
                    description: The unique identifier of the webhook.
                  webhookUrl:
                    type: string
                    format: uri
                    description: The URL where webhook events are sent.
                  name:
                    type: string
                    description: The name of the webhook.
                  eventTypes:
                    type: array
                    items:
                      type: string
                      description: The event types that the webhook is subscribed to.
                  hasSigningSecret:
                    type: boolean
                    description: Whether HMAC signing secret is used for this webhook.
                    example: true
        '401':
          description: Unauthorized - Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
        '404':
          description: Not Found - Webhook not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
      x-codeSamples:
      - lang: curl
        source: "curl -X GET \"https://docs-api.formify.eu/v1/webhooks/{webhookId}\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\""
      - lang: JavaScript
        source: "const response = await fetch(\"https://docs-api.formify.eu/v1/webhooks/{webhookId}\", {\n  method: \"GET\",\n  headers: {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n  }\n});\n\nconst data = await response.json();\nconsole.log(data);"
      - lang: Python
        source: "import requests\n\nurl = \"https://docs-api.formify.eu/v1/webhooks/{webhookId}\"\nheaders = {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n}\n\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
    delete:
      tags:
      - Webhooks
      summary: Delete a webhook
      description: This endpoint deletes a registered webhook.
      operationId: deleteWebhook
      parameters:
      - in: path
        name: webhookId
        required: true
        schema:
          type: string
          format: uuid
        description: The unique identifier of the webhook to delete.
      responses:
        '204':
          description: Webhook deleted successfully. No content returned.
        '401':
          description: Unauthorized - Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
        '404':
          description: Not Found - Webhook not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
      x-codeSamples:
      - lang: curl
        source: "curl -X DELETE \"https://docs-api.formify.eu/v1/webhooks/{webhookId}\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\""
      - lang: JavaScript
        source: "const response = await fetch(\"https://docs-api.formify.eu/v1/webhooks/{webhookId}\", {\n  method: \"DELETE\",\n  headers: {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n  }\n});\n\nconsole.log(response.status); // 204"
      - lang: Python
        source: "import requests\n\nurl = \"https://docs-api.formify.eu/v1/webhooks/{webhookId}\"\nheaders = {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n}\n\nresponse = requests.delete(url, headers=headers)\nprint(response.status_code)  # 204"
  /webhooks/{webhookId}/rotate-secret:
    post:
      tags:
      - Webhooks
      summary: Rotate webhook signing secret
      description: Generates a new signing secret for the specified webhook. The old secret is immediately invalidated. Make sure to update your verification logic with the new secret.
      operationId: rotateWebhookSecret
      parameters:
      - name: webhookId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The unique identifier of the webhook.
      - name: errorLanguage
        in: query
        schema:
          type: string
          enum:
          - en
          - sv
          - es
          default: en
        description: Language for the error message
      responses:
        '200':
          description: Secret rotated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhookId:
                    type: string
                    format: uuid
                    description: The unique identifier of the webhook.
                  signingSecret:
                    type: string
                    description: The new signing secret.
                    example: whsec_bmV3IHNlY3JldCBnZW5lcmF0ZWQ=
        '401':
          description: Unauthorized - Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
        '403':
          description: Forbidden — webhook belongs to another account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse403'
        '404':
          description: Webhook not found or disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
      x-codeSamples:
      - lang: curl
        source: "curl -X POST \"https://docs-api.formify.eu/v1/webhooks/{webhookId}/rotate-secret\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\""
      - lang: JavaScript
        source: "const response = await fetch(\"https://docs-api.formify.eu/v1/webhooks/{webhookId}/rotate-secret\", {\n  method: \"POST\",\n  headers: {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n  }\n});\n\nconst data = await response.json();\nconsole.log(data);"
      - lang: Python
        source: "import requests\n\nurl = \"https://docs-api.formify.eu/v1/webhooks/{webhookId}/rotate-secret\"\nheaders = {\n    \"Authorization\": \"Bearer YOUR_ACCESS_TOKEN\"\n}\n\nresponse = requests.post(url, headers=headers)\nprint(response.json())"
components:
  schemas:
    ErrorResponse401:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Unauthorized
        code:
          type: integer
          example: 401
        language:
          type: string
          example: en
    ErrorResponse403:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Forbidden
        code:
          type: integer
          example: 403
        language:
          type: string
          example: en
    ErrorResponse404:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Not Found
        code:
          type: integer
          example: 404
        language:
          type: string
          example: en
    ErrorResponse500:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Internal Server Error
        code:
          type: integer
          example: 500
        language:
          type: string
          example: en
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'HTTP Basic Authentication for traditional OAuth clients. Send `Authorization: Basic base64(client_id:client_secret)`.'
    ApiKeyAuth:
      type: http
      scheme: ApiKey
      description: 'Formify API key authentication for `POST /auth/token` only. Send the API key using the HTTP authorization scheme format `Authorization: ApiKey sk_live_YOUR_API_KEY` to exchange it for a short-lived Bearer access token. Test keys use the same format with the `sk_test_` prefix.'
    OAuth2:
      type: oauth2
      description: OAuth2 Authentication. Allows third-party systems to access the API on behalf of the user and their account after authorization.
      flows:
        authorizationCode:
          authorizationUrl: https://docs-api.formify.eu/v1/oauth/authorize
          tokenUrl: https://docs-api.formify.eu/v1/oauth/token
          scopes:
            read: Allows reading documents and their metadata
            write: Allows modifying documents and sending signature requests
externalDocs:
  description: Formify website
  url: https://formify.eu
x-tagGroups:
- name: Authentication
  tags:
  - oauth
  - auth
- name: Documents
  tags:
  - files
  - docs
  - drafts
  - templates
  - links
- name: Account & User
  tags:
  - user
  - account
- name: Webhooks
  tags:
  - webhooks