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

# Subscribe to an event

> Registers a URL to be POSTed whenever the named event happens in the workspace.

Built for REST Hook integrations that create and destroy subscriptions as users enable and disable their automations.

Returns the subscription id, which is what unsubscribes it, and a `secret` shown only here: every delivery carries `X-Hero-Signature: t=<unix seconds>,v1=<hex>`, the HMAC-SHA256 of `<t>.<raw body>` under that secret.



## OpenAPI

````yaml post /subscription
openapi: 3.1.0
info:
  title: HERO API
  version: current
  description: |-
    The HERO REST API.

    See https://developers.myhero.so for the rendered docs.
servers:
  - url: https://app.myhero.so
security: []
paths:
  /subscription:
    post:
      tags:
        - Subscriptions
      summary: Subscribe to an event
      description: >-
        Registers a URL to be POSTed whenever the named event happens in the
        workspace.


        Built for REST Hook integrations that create and destroy subscriptions
        as users enable and disable their automations.


        Returns the subscription id, which is what unsubscribes it, and a
        `secret` shown only here: every delivery carries `X-Hero-Signature:
        t=<unix seconds>,v1=<hex>`, the HMAC-SHA256 of `<t>.<raw body>` under
        that secret.
      operationId: createWebhookSubscription
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                event:
                  type: string
                  enum:
                    - row.created
                    - row.updated
                    - row.deleted
                    - cell.changed
                    - clause.added
                    - clause.edited
                    - clause.deleted
                    - term.defined
                    - term.removed
                    - signature.signed
                    - document.fullySigned
                    - document.signaturesVoided
                    - document.created
                    - document.updated
                    - document.moved
                    - document.published
                    - document.duplicated
                    - document.deleted
                    - document.renamed
                    - document.newVersion
                    - document.restoreVersion
                    - workspace.memberJoined
                    - workspace.memberLeft
                    - document.collaboratorAdded
                    - document.collaboratorRemoved
                    - table.created
                    - table.deleted
                    - column.added
                    - column.deleted
                    - project.created
                targetUrl:
                  type: string
                  format: uri
                workspaceId:
                  type: string
                  minLength: 1
                projectIds:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: array
                      items:
                        type: string
                        minLength: 1
                projectId:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: array
                      items:
                        type: string
                        minLength: 1
                tableIds:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: array
                      items:
                        type: string
                        minLength: 1
                tableId:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: array
                      items:
                        type: string
                        minLength: 1
              required:
                - event
                - targetUrl
      responses:
        '201':
          description: 201 response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      _id:
                        type: string
                      event:
                        type: string
                        enum:
                          - row.created
                          - row.updated
                          - row.deleted
                          - cell.changed
                          - clause.added
                          - clause.edited
                          - clause.deleted
                          - term.defined
                          - term.removed
                          - signature.signed
                          - document.fullySigned
                          - document.signaturesVoided
                          - document.created
                          - document.updated
                          - document.moved
                          - document.published
                          - document.duplicated
                          - document.deleted
                          - document.renamed
                          - document.newVersion
                          - document.restoreVersion
                          - workspace.memberJoined
                          - workspace.memberLeft
                          - document.collaboratorAdded
                          - document.collaboratorRemoved
                          - table.created
                          - table.deleted
                          - column.added
                          - column.deleted
                          - project.created
                      targetUrl:
                        type: string
                        format: uri
                      workspaceId:
                        type: string
                      projectIds:
                        type: array
                        items:
                          type: string
                      tableIds:
                        type: array
                        items:
                          type: string
                      createdAt:
                        type: number
                      lastDeliveredAt:
                        type: number
                      failureCount:
                        type: number
                      isDisabled:
                        type: boolean
                      secret:
                        type: string
                        description: |-
                          Signing key for X-Hero-Signature.

                          Shown once — store it now; listing never returns it.
                    required:
                      - _id
                      - event
                      - targetUrl
                      - workspaceId
                      - createdAt
                      - failureCount
                      - secret
                required:
                  - data
        '400':
          description: 400 response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: |-
                      Error class name (e.g.

                      ValidationError, NotFound)
                  message:
                    type: string
                    description: Human-readable error message
                  details:
                    type: array
                    items: {}
                required:
                  - error
                  - message
        '403':
          description: 403 response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: |-
                      Error class name (e.g.

                      ValidationError, NotFound)
                  message:
                    type: string
                    description: Human-readable error message
                  details:
                    type: array
                    items: {}
                required:
                  - error
                  - message
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: HERO personal access token

````

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