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

# Create a webhook subscription

> Subscribes a URL to decision webhooks, in addition to the workspace webhook URL set in the console.
Built for REST hooks such as Zapier: subscribe when an automation is turned on, delete the
subscription when it is turned off. A workspace can have up to 50.

Each delivery has the workspace webhook's body and headers, signed with the secret key that
signed this request while that key exists, and with the active secret key after it is deleted.
Unless `include_document_data` is true, the body leaves out `document`, `fingerprint_signals` and
`manual_moderation.performed_by`. A delivery answered with `410 Gone` deletes the subscription.



## OpenAPI

````yaml /openapi.json post /webhook-subscriptions
openapi: 3.1.0
info:
  title: API Reference
  version: 1.0.0
  description: >-
    ProofAge is an identity verification and age estimation API. Use this API to
    create verification sessions, upload media (selfies and documents), and
    receive decisions via webhooks.
servers:
  - url: https://api.proofage.net/v1
    description: API
security:
  - apiKey: []
    hmacSignature: []
paths:
  /webhook-subscriptions:
    post:
      tags:
        - WebhookSubscription
      summary: Create a webhook subscription
      description: >-
        Subscribes a URL to decision webhooks, in addition to the workspace
        webhook URL set in the console.

        Built for REST hooks such as Zapier: subscribe when an automation is
        turned on, delete the

        subscription when it is turned off. A workspace can have up to 50.


        Each delivery has the workspace webhook's body and headers, signed with
        the secret key that

        signed this request while that key exists, and with the active secret
        key after it is deleted.

        Unless `include_document_data` is true, the body leaves out `document`,
        `fingerprint_signals` and

        `manual_moderation.performed_by`. A delivery answered with `410 Gone`
        deletes the subscription.
      operationId: createWebhookSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreWebhookSubscriptionRequest'
      responses:
        '201':
          description: >-
            The subscription. `statuses` is null when it receives every decision
            status.
          content:
            application/json:
              schema:
                type: object
                examples:
                  - id: 0199c4b2-7d1e-7a3f-9c0e-5b6a7c8d9e0f
                    url: https://hooks.zapier.com/hooks/standard/12345678/abcdef/
                    statuses:
                      - approved
                      - declined
                    include_document_data: false
                    created_at: '2026-10-08T12:00:00+00:00'
                properties:
                  id:
                    type: string
                  url:
                    type: string
                  statuses:
                    type:
                      - array
                      - 'null'
                    items:
                      type: string
                  include_document_data:
                    type: boolean
                  created_at:
                    type: string
                required:
                  - id
                  - url
                  - statuses
                  - include_document_data
                  - created_at
        '422':
          description: >-
            The workspace already has 50 webhook subscriptions
            (`WEBHOOK_SUBSCRIPTION_LIMIT`), or a field is invalid (`message` and
            `errors` by field).
          content:
            application/json:
              schema:
                examples:
                  - error:
                      code: WEBHOOK_SUBSCRIPTION_LIMIT
                      message: >-
                        A workspace can have at most 50 webhook subscriptions.
                        Delete one first.
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                          message:
                            type: string
                        required:
                          - code
                          - message
                    required:
                      - error
                  - type: object
                    properties:
                      message:
                        type: string
                      errors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                    required:
                      - message
                      - errors
components:
  schemas:
    StoreWebhookSubscriptionRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: >-
            Where ProofAge POSTs the decision webhooks, signed like the
            workspace webhook. It must be a public URL: private, local and
            cloud-metadata addresses are refused.
          maxLength: 2048
        include_document_data:
          type: boolean
          description: >-
            Include the document read from the identity document (names, date of
            birth, document number), the fingerprint signals (IP address,
            timezones) and the name and email of the operator who moderated. Off
            by default, so personal data stays out of the subscriber's logs.
          default: false
        statuses:
          type:
            - array
            - 'null'
          description: >-
            Only send these statuses: `approved`, `declined`,
            `resubmission_requested`, `review`, `abandoned`, `expired`. Omit it,
            or send null, for all of them.
          items:
            type: string
            enum:
              - approved
              - declined
              - resubmission_requested
              - abandoned
              - expired
              - review
      required:
        - url
      title: StoreWebhookSubscriptionRequest
  securitySchemes:
    apiKey:
      type: apiKey
      description: Your workspace public key (pk_test_… or pk_live_…).
      in: header
      name: X-API-Key
    hmacSignature:
      type: apiKey
      description: >-
        HMAC-SHA256 of the request, hex-encoded, keyed with the workspace secret
        key. See API authentication.
      in: header
      name: X-HMAC-Signature

````

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