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

# Create a webhook endpoint

> Creates a webhook endpoint that receives signed HTTP requests for the events it subscribes to. Needs the Business plan or above.

The response is the only place, besides the Rotate a signing secret operation, that returns the endpoint's signing secret. Store it now: it cannot be read again.

The URL must use https, a public host name, and port 443 (the default) or 8443. IP addresses, local names such as `localhost`, and host names that resolve to a private, loopback or link-local address are refused (`url_not_allowed`), and Lora does not follow redirects when it sends. A workspace can have ten endpoints of its own, and each URL once.

An endpoint receives only events created after it was created. Nothing is sent for the past.

Send an `Idempotency-Key` to retry safely: for 24 hours, per workspace and API key, the same key with the same body returns the endpoint the first request created, without the secret (`200`), while that endpoint still exists. The same key with a different body is a `409`. A retry is answered from what was stored, without checking the URL again, but it still needs the Business plan, so it answers `402` after a downgrade. Rotate the secret if the response with the secret was lost.



## OpenAPI

````yaml /openapi.json post /v1/webhooks
openapi: 3.1.0
info:
  title: Lora API
  version: 1.0.0
  description: >-
    Lora REST API for managing workspace shortcuts, folders, tags, webhook
    endpoints, and QR codes.


    ## Versioning

    All stable endpoints are prefixed with `/v1/`. Breaking changes ship under a
    new path prefix (for example `/v2/`).

    Non-breaking additions (new optional fields, new endpoints) may land in the
    current version.

    Deprecated endpoints are announced in the [developer
    docs](https://uselora.dev/essentials/versioning) before removal.


    ## Authentication

    Send `Authorization: Bearer <api_key>` on every request except `GET /v1/qr`,
    which also accepts anonymous callers. API keys are workspace-scoped and
    carry named scopes (for example `shortcuts.write`); each scoped operation's
    `security` requirement lists the one scope it needs (`GET /v1/qr` needs
    none), so request a key with only those.


    ## Errors

    4xx and 5xx responses use a typed JSON envelope: `{ error, code?, requestId,
    traceId?, fieldErrors?, required_scope?, current_plan?, required_capability?
    }`.

    See components `ErrorResponse`, `ErrorWithFieldErrors`,
    `PaymentRequiredError`, `ForbiddenError`, `PayloadTooLargeError`, and
    `InternalError`.


    ## Rate limits

    Successful responses include `RateLimit-Limit`, `RateLimit-Remaining`, and
    `RateLimit-Reset` (IETF RateLimit fields).

    429 responses include `Retry-After` (seconds). Authenticated callers are
    bucketed per API key; anonymous QR endpoints are bucketed per IP.


    ## Discovery

    - OpenAPI spec: `GET https://api.uselora.com/openapi.json` (also `GET
    https://api.uselora.com/`)

    - RFC 9727 catalog: `GET https://www.uselora.com/.well-known/api-catalog`

    - MCP manifest: `GET https://www.uselora.com/.well-known/mcp` (server card
    at `/.well-known/mcp/server-card.json`)

    - MCP Streamable HTTP endpoint: `POST https://api.uselora.com/mcp`
servers:
  - url: https://api.uselora.com
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/webhooks:
    post:
      tags:
        - Webhooks
      summary: Create a webhook endpoint
      description: >-
        Creates a webhook endpoint that receives signed HTTP requests for the
        events it subscribes to. Needs the Business plan or above.


        The response is the only place, besides the Rotate a signing secret
        operation, that returns the endpoint's signing secret. Store it now: it
        cannot be read again.


        The URL must use https, a public host name, and port 443 (the default)
        or 8443. IP addresses, local names such as `localhost`, and host names
        that resolve to a private, loopback or link-local address are refused
        (`url_not_allowed`), and Lora does not follow redirects when it sends. A
        workspace can have ten endpoints of its own, and each URL once.


        An endpoint receives only events created after it was created. Nothing
        is sent for the past.


        Send an `Idempotency-Key` to retry safely: for 24 hours, per workspace
        and API key, the same key with the same body returns the endpoint the
        first request created, without the secret (`200`), while that endpoint
        still exists. The same key with a different body is a `409`. A retry is
        answered from what was stored, without checking the URL again, but it
        still needs the Business plan, so it answers `402` after a downgrade.
        Rotate the secret if the response with the secret was lost.
      operationId: createWebhookEndpoint
      parameters:
        - description: >-
            A unique value for this request, up to 255 characters, to make
            retrying it safe. Remembered for 24 hours per workspace and API key.
          in: header
          name: Idempotency-Key
          required: false
          schema:
            maxLength: 255
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookEndpointRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplayedWebhookEndpoint'
          description: >-
            A retry of a request that already created an endpoint: that
            endpoint, without its secret.
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedWebhookEndpoint'
          description: The created endpoint, with its signing secret.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookUrlRefusedError'
          description: >-
            The body failed validation or was not valid JSON
            (`validation_error`, `invalid_json`), the `Idempotency-Key` is too
            long (`invalid_idempotency_key`), or Lora refused the URL
            (`url_not_allowed`; `reason` says which rule).
          headers:
            X-Lora-Request-Id:
              description: >-
                Request correlation identifier. Matches the `requestId` field in
                the JSON error body.
              schema:
                type: string
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            Missing, malformed, unknown or revoked API key. A key that was
            disabled by a downgrade answers with `apikey_disabled`.
          headers:
            X-Lora-Request-Id:
              description: >-
                Request correlation identifier. Matches the `requestId` field in
                the JSON error body.
              schema:
                type: string
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequiredError'
          description: >-
            The workspace plan does not include webhooks
            (`plan_requires_upgrade`: Business and above), or the workspace
            already has ten endpoints (`quota_exceeded`).
          headers:
            X-Lora-Request-Id:
              description: >-
                Request correlation identifier. Matches the `requestId` field in
                the JSON error body.
              schema:
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
          description: >-
            The key lacks the required scope (`insufficient_scope`, with
            `required_scope`), its owner is no longer an owner or admin of the
            workspace (`insufficient_role`), or its owner is no longer a member
            of the workspace (`no_permission`).
          headers:
            X-Lora-Request-Id:
              description: >-
                Request correlation identifier. Matches the `requestId` field in
                the JSON error body.
              schema:
                type: string
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            The URL is already an endpoint of the workspace (`url_in_use`), or
            the `Idempotency-Key` was used with a different body
            (`idempotency_key_reused`).
          headers:
            X-Lora-Request-Id:
              description: >-
                Request correlation identifier. Matches the `requestId` field in
                the JSON error body.
              schema:
                type: string
        '413':
          description: >-
            The request body exceeded the size limit. The body is rejected
            before being parsed, so no partial write occurred; retrying with a
            smaller payload will succeed.
          headers:
            X-Lora-Request-Id:
              description: >-
                Request correlation identifier. Matches the `requestId` field in
                the JSON error body.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayloadTooLargeError'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Rate limit exceeded. Wait `Retry-After` seconds before retrying.
          headers:
            Retry-After:
              description: Seconds until the rate-limit window resets.
              schema:
                type: integer
                minimum: 1
            X-Lora-Request-Id:
              description: >-
                Request correlation identifier. Matches the `requestId` field in
                the JSON error body.
              schema:
                type: string
        '500':
          description: >-
            An unexpected failure on the server. The body is `{ error:
            <message>, code: "internal_error", requestId: <id> }`, plus
            `traceId` when available. Retry idempotent operations with
            exponential backoff. A write may already have applied; reconcile its
            state before retrying.
          headers:
            X-Lora-Request-Id:
              description: >-
                Request correlation identifier. Matches the `requestId` field in
                the JSON error body.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      security:
        - bearerAuth:
            - webhooks.write
components:
  schemas:
    CreateWebhookEndpointRequest:
      type: object
      properties:
        description:
          type:
            - string
            - 'null'
          maxLength: 200
          description: >-
            A label for the endpoint, up to 200 characters. It appears in the
            emails Lora sends about the endpoint.
          examples:
            - Sync to the intranet
        events:
          minItems: 1
          maxItems: 3
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventName'
          description: >-
            The events the endpoint receives. An endpoint gets only events
            created after it was created, or after the event was added to this
            list: nothing is sent for the past.
        url:
          type: string
          minLength: 1
          maxLength: 2048
          description: >-
            The HTTPS URL that receives events. It must resolve to a public
            address: IP addresses, local names and private, loopback and
            link-local ranges are refused, and redirects are not followed. Each
            URL can be an endpoint once per workspace.
          examples:
            - https://example.com/hooks/lora
      required:
        - events
        - url
      additionalProperties: false
      description: Payload to create a webhook endpoint.
    ReplayedWebhookEndpoint:
      $ref: '#/components/schemas/WebhookEndpoint'
      description: >-
        The endpoint an earlier request with the same `Idempotency-Key` created.
        It carries no secret: rotate the secret if it was lost.
    CreatedWebhookEndpoint:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
          description: ISO 8601 creation time.
        description:
          description: The endpoint's label, or null when it has none.
          type:
            - string
            - 'null'
        disabledReason:
          description: >-
            Why the endpoint is off, or null while it is on. `manual`: someone
            turned it off. `gone`: the receiver answered 410 Gone. `failing`:
            for five days no delivery succeeded, and at least five deliveries
            ran out of retries.
          type:
            - string
            - 'null'
          enum:
            - manual
            - gone
            - failing
            - null
        enabled:
          type: boolean
          description: >-
            Whether events are delivered. Turning an endpoint off cancels the
            deliveries still waiting for it.
        events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventName'
          description: The events the endpoint receives.
        id:
          type: string
          pattern: ^wh_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          description: The endpoint's unique ID.
          examples:
            - wh_0198f2a4-7c1b-7d3e-9a52-3f6b1c2d4e5f
        previousSecretExpiresAt:
          description: >-
            While a rotated secret still signs next to the new one, when it
            stops, ISO 8601; otherwise null.
          type:
            - string
            - 'null'
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        source:
          type: string
          enum:
            - api
            - subscription
          description: >-
            `api`: created with an API key. `subscription`: made by an
            integration such as Zapier, which owns it. You can read it here;
            only the integration changes or deletes it.
        updatedAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
          description: ISO 8601 time of the last change.
        url:
          type: string
          description: >-
            The URL that receives events. For an endpoint an integration made
            (`source: subscription`), only the host is shown.
        secret:
          type: string
          description: >-
            The signing secret, `whsec_` and base64. Shown here once and never
            again: store it now. Verify requests with it using any Standard
            Webhooks library.
          examples:
            - whsec_your_signing_secret
      required:
        - createdAt
        - description
        - disabledReason
        - enabled
        - events
        - id
        - previousSecretExpiresAt
        - source
        - updatedAt
        - url
        - secret
      additionalProperties: false
      description: >-
        A newly created webhook endpoint with its signing secret, the only time
        the secret is returned besides a rotation.
    WebhookUrlRefusedError:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        fieldErrors:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: array
            items:
              type: string
        requestId:
          type: string
          description: >-
            Correlation identifier for support/debugging. Equals the
            `X-Lora-Request-Id` response header.
        traceId:
          description: >-
            Trace identifier when available for this request. 32-character
            lowercase hex string.
          type: string
          pattern: ^[0-9a-f]{32}$
        reason:
          description: >-
            Set when `code` is `url_not_allowed`: the rule that refused the URL.
            `not_a_url`: not a valid URL. `scheme`: not https. `userinfo`: the
            URL contains a username or password. `ip_literal`: the host is an IP
            address. `host`: the host is a local name, has no domain, or ends in
            a dot. `port`: the port is neither 443 nor 8443. `dns`: the host
            name does not resolve, or the lookup takes longer than five seconds.
            `private_address`: the host name resolves to a private, loopback or
            link-local address.
          enum:
            - not_a_url
            - scheme
            - userinfo
            - ip_literal
            - host
            - port
            - dns
            - private_address
          type: string
      required:
        - error
        - requestId
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        requestId:
          type: string
          description: >-
            Correlation identifier for support/debugging. Equals the
            `X-Lora-Request-Id` response header.
        traceId:
          description: >-
            Trace identifier when available for this request. 32-character
            lowercase hex string.
          type: string
          pattern: ^[0-9a-f]{32}$
      required:
        - error
        - requestId
      additionalProperties: false
    PaymentRequiredError:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          enum:
            - plan_requires_upgrade
            - quota_exceeded
        requestId:
          type: string
          description: >-
            Correlation identifier for support/debugging. Equals the
            `X-Lora-Request-Id` response header.
        traceId:
          description: >-
            Trace identifier when available for this request. 32-character
            lowercase hex string.
          type: string
          pattern: ^[0-9a-f]{32}$
        current_plan:
          description: The workspace plan when the response includes it.
          type: string
        required_capability:
          description: The required plan capability when the response includes it.
          type: string
      required:
        - error
        - code
        - requestId
      additionalProperties: false
    ForbiddenError:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        requestId:
          type: string
          description: >-
            Correlation identifier for support/debugging. Equals the
            `X-Lora-Request-Id` response header.
        traceId:
          description: >-
            Trace identifier when available for this request. 32-character
            lowercase hex string.
          type: string
          pattern: ^[0-9a-f]{32}$
        required_scope:
          description: >-
            Set when `code` is `insufficient_scope`. The exact scope name the
            route required, e.g. `shortcuts.write`.
          type: string
      required:
        - error
        - requestId
      additionalProperties: false
    PayloadTooLargeError:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          const: payload_too_large
        requestId:
          type: string
          description: >-
            Correlation identifier for support/debugging. Equals the
            `X-Lora-Request-Id` response header.
        traceId:
          description: >-
            Trace identifier when available for this request. 32-character
            lowercase hex string.
          type: string
          pattern: ^[0-9a-f]{32}$
      required:
        - error
        - code
        - requestId
      additionalProperties: false
    InternalError:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          const: internal_error
        requestId:
          type: string
          description: >-
            Correlation identifier for support/debugging. Equals the
            `X-Lora-Request-Id` response header.
        traceId:
          description: >-
            Trace identifier when available for this request. 32-character
            lowercase hex string.
          type: string
          pattern: ^[0-9a-f]{32}$
      required:
        - error
        - code
        - requestId
      additionalProperties: false
    WebhookEventName:
      type: string
      enum:
        - shortcut.created
        - shortcut.updated
        - shortcut.deleted
      description: >-
        An event type. `shortcut.created`: a visible shortcut was inserted, or a
        shortcut became visible to the workspace. `shortcut.updated`: a shortcut
        was updated. `shortcut.deleted`: a shortcut was removed, or left
        workspace visibility (made private or unlisted).
      examples:
        - shortcut.created
    WebhookEndpoint:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
          description: ISO 8601 creation time.
        description:
          description: The endpoint's label, or null when it has none.
          type:
            - string
            - 'null'
        disabledReason:
          description: >-
            Why the endpoint is off, or null while it is on. `manual`: someone
            turned it off. `gone`: the receiver answered 410 Gone. `failing`:
            for five days no delivery succeeded, and at least five deliveries
            ran out of retries.
          type:
            - string
            - 'null'
          enum:
            - manual
            - gone
            - failing
            - null
        enabled:
          type: boolean
          description: >-
            Whether events are delivered. Turning an endpoint off cancels the
            deliveries still waiting for it.
        events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventName'
          description: The events the endpoint receives.
        id:
          type: string
          pattern: ^wh_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          description: The endpoint's unique ID.
          examples:
            - wh_0198f2a4-7c1b-7d3e-9a52-3f6b1c2d4e5f
        previousSecretExpiresAt:
          description: >-
            While a rotated secret still signs next to the new one, when it
            stops, ISO 8601; otherwise null.
          type:
            - string
            - 'null'
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        source:
          type: string
          enum:
            - api
            - subscription
          description: >-
            `api`: created with an API key. `subscription`: made by an
            integration such as Zapier, which owns it. You can read it here;
            only the integration changes or deletes it.
        updatedAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
          description: ISO 8601 time of the last change.
        url:
          type: string
          description: >-
            The URL that receives events. For an endpoint an integration made
            (`source: subscription`), only the host is shown.
      required:
        - createdAt
        - description
        - disabledReason
        - enabled
        - events
        - id
        - previousSecretExpiresAt
        - source
        - updatedAt
        - url
      additionalProperties: false
      description: >-
        A webhook endpoint. Its signing secret is never part of it: it is
        returned once, when the endpoint is created or its secret rotated.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Workspace API key (`lora_sk_…`) sent as `Authorization: Bearer
        <api_key>`. Each scoped operation names the scope it requires in its
        `security` requirement, for example `shortcuts.write`; a key without it
        receives `403` with `code: insufficient_scope`. `GET /v1/qr` also
        accepts anonymous requests and requires no scope.

````

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