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

# Create webhook subscription

> Available to any API-eligible account with a verified email address.

Stores a webhook subscription for your personal workspace or for a business workspace where you are an owner or admin. Business members and other workspaces return `404`. Business subscriptions belong to the workspace, not to the key owner, so other owners and admins can list and delete them.

In a business workspace, `contact.created` fires once for each new business contact shared into that workspace. Its `data.contact_id` is the business contact `id` returned by the list contacts endpoint. Updates, repeat shares, restores, and imported or backfilled history do not fire it, and events from before the subscription was created are not replayed.

The URL must be an absolute HTTPS URL without embedded credentials or a fragment. At least one event is required, and duplicate event names are stored once. No request is sent to the URL during registration.

Repeated calls create separate subscriptions, including for the same URL. Store the signing_secret returned on creation securely; it cannot be retrieved again. If the response is lost, delete the subscription and create a replacement.

Requires the `blinq:webhooks:write` and `blinq:contacts:read` scopes.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/workspaces/{workspace_id}/webhooks
openapi: 3.1.0
info:
  title: Blinq Public API
  version: 1.0.0
  description: >-
    The Blinq API provides programmatic access to your contacts and notes.
    Connect Blinq to your existing tools, keep contact records in sync, and
    build workflows on note summaries and transcripts.


    API access requires a [Blinq Pro or Business plan](https://blinq.me/pricing)
    and a verified email address. Keys are personal and scoped: they never grant
    access beyond what their owner can already see.


    ## Access scopes


    Choose one or more scopes when creating a key.


    | Scope | Grants access to |

    | --- | --- |

    | `blinq:contacts:read` | Your personal contacts. Business owners and admins
    can list contacts; members can retrieve a visible contact by a known ID. |

    | `blinq:cards:read` | Lightweight card summaries and sharing links in your
    personal workspace and business workspaces you own or administer. |

    | `blinq:notes:read` | Your own notes and transcripts. |

    | `blinq:identity:read` | Your identity and the workspaces you belong to. |

    | `blinq:webhooks:read` | The webhook subscriptions stored for your personal
    workspace. |

    | `blinq:webhooks:write` | Creating and deleting webhook subscriptions for
    your personal workspace. Creating also requires `blinq:contacts:read`. |


    ## Creating and revoking keys


    1. In the Blinq web app, open Settings > API keys.

    2. Select **Create new key**, choose a name and the scopes your integration
    needs, then select **Generate API key**.

    3. Copy the key when it is shown. The secret is displayed only once; store
    it securely.


    To revoke a key, return to Settings > API keys and select **Revoke**. A
    revoked key stops authenticating new requests immediately.


    ## Quick start


    Send your key to `https://api.blinq.me` as `Authorization: Bearer
    <api-key>`. In the documentation playground, enter only the key, without
    `Bearer`.


    List your notes (requires `blinq:notes:read`):


    ```bash

    curl 'https://api.blinq.me/v1/notes?limit=5' \
      -H 'Authorization: Bearer <api-key>'
    ```


    Contact routes are scoped to one workspace. `GET /v1/workspaces` (requires
    `blinq:identity:read`) discovers workspace IDs; listing contacts from a
    known workspace ID needs only `blinq:contacts:read`:


    ```bash

    curl 'https://api.blinq.me/v1/workspaces/<workspace-id>/contacts?limit=5' \
      -H 'Authorization: Bearer <api-key>'
    ```


    ## Errors


    All errors return a JSON body with `status` (the HTTP status code), `error`
    (the HTTP status name, such as `Bad Request`), `code` (a machine-readable
    error code), `message` (a human-readable description; wording may change, so
    branch on `code` instead), and `request_id` (the unique ID of the request,
    also returned as the `X-Request-Id` header). Validation errors may add a
    `details` array naming each parameter or body field that failed.


    Any route can return `400` when query parameters or the body are invalid
    (unknown query parameters are rejected), `401` when the API key is missing
    or invalid, `403` when the key is missing a required scope, its owner lacks
    permission, or the account plan does not include the operation, and `429`
    when the rate limit is reached (see Rate limits). Any route can also return
    `500` when an unexpected error occurs (quote `request_id` when contacting
    support) and `503` when API key verification or the requested operation is
    unavailable.


    The responses documented on each route below list only the status codes
    specific to that operation.


    ## Rate limits


    Each person can make up to **25 requests in any 5-second window**, or **300
    requests per minute** at a steady rate. The quota is shared across all of
    their API keys; creating more keys does not increase it. When the limit is
    reached, the API returns `429 Too Many Requests` with a `Retry-After` header
    in seconds. Wait that long before retrying.
servers:
  - url: https://api.blinq.me
security: []
tags:
  - name: Contacts
    description: >-
      List contact summaries or get contact details, saved contact notes, and
      linked note metadata.


      Contact lists include personal contacts and contacts in business
      workspaces the authenticated user owns or administers. Business members
      receive an empty list, but can retrieve a visible business contact by
      known ID.


      Requires the `blinq:contacts:read` scope.
  - name: Cards
    description: >-
      List or get lightweight card summaries: the name, title, company,
      department, and public sharing URL on each card.


      Card routes are scoped to one workspace: your personal workspace or a
      business workspace you own or administer. Business members cannot read
      team cards.


      Requires the `blinq:cards:read` scope.
  - name: Notes
    description: >-
      List note metadata, get note content and transcripts, search notes, or
      generate answers with citations.


      Only notes owned by the authenticated user are accessible.


      Requires the `blinq:notes:read` scope.
  - name: Workspaces
    description: >-
      List every workspace the authenticated user belongs to, with its type and
      their role.


      Use a known workspace ID directly, or discover it here. Business contact
      listing requires owner or admin; retrieving a visible contact by known ID
      also allows members.


      Requires the `blinq:identity:read` scope.
  - name: Me
    description: >-
      Identify the user the supplied API key acts as, with their ID and sign-in
      email.


      Confirm whose account an integration is accessing before listing
      workspaces or fetching data.


      Requires the `blinq:identity:read` scope.
  - name: Webhooks
    description: >-
      Create, list, and delete webhook subscriptions for your personal
      workspace. Only `contact.created` is supported, and business workspaces
      are not supported.


      Creation returns a signing secret once; store it securely to verify
      deliveries. Registration sends no request to the subscribed URL. Delivery
      is handled by the separate webhook service when enabled.


      Listing requires the `blinq:webhooks:read` scope. Creating and deleting
      require `blinq:webhooks:write`; creating also requires
      `blinq:contacts:read`.
paths:
  /v1/workspaces/{workspace_id}/webhooks:
    post:
      tags:
        - Webhooks
      summary: Create webhook subscription
      description: >-
        Available to any API-eligible account with a verified email address.


        Stores a webhook subscription for your personal workspace or for a
        business workspace where you are an owner or admin. Business members and
        other workspaces return `404`. Business subscriptions belong to the
        workspace, not to the key owner, so other owners and admins can list and
        delete them.


        In a business workspace, `contact.created` fires once for each new
        business contact shared into that workspace. Its `data.contact_id` is
        the business contact `id` returned by the list contacts endpoint.
        Updates, repeat shares, restores, and imported or backfilled history do
        not fire it, and events from before the subscription was created are not
        replayed.


        The URL must be an absolute HTTPS URL without embedded credentials or a
        fragment. At least one event is required, and duplicate event names are
        stored once. No request is sent to the URL during registration.


        Repeated calls create separate subscriptions, including for the same
        URL. Store the signing_secret returned on creation securely; it cannot
        be retrieved again. If the response is lost, delete the subscription and
        create a replacement.


        Requires the `blinq:webhooks:write` and `blinq:contacts:read` scopes.
      operationId: createWebhook
      parameters:
        - schema:
            type: string
            minLength: 1
          in: path
          name: workspace_id
          required: true
          description: >-
            The workspace ID: your individual workspace, or a business workspace
            where you are an owner or admin. Use an `id` returned by the list
            workspaces endpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  minLength: 1
                  maxLength: 2048
                  description: >-
                    The HTTPS destination URL for deliveries. Credentials and
                    fragments are rejected. The stored URL is the normalized
                    form, preserving query parameters.
                events:
                  minItems: 1
                  type: array
                  items:
                    type: string
                    enum:
                      - contact.created
                    description: >-
                      An event the subscription receives. `contact.created`
                      fires when a contact is created in your personal
                      workspace, or once for each new business contact shared
                      into a business workspace. Business payloads carry the
                      business contact `id` returned by the list contacts
                      endpoint.
                  description: >-
                    The events to receive. At least one is required; duplicates
                    are stored once.
              required:
                - url
                - events
              additionalProperties: false
      responses:
        '201':
          description: The identity of the newly stored subscription.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The created subscription ID.
                  signing_secret:
                    type: string
                    description: >-
                      Store this signing secret securely. It is returned only on
                      creation and cannot be retrieved again.
                required:
                  - id
                  - signing_secret
                additionalProperties: false
                description: The identity of the newly stored subscription.
              example:
                id: subscription-id
                signing_secret: whsec_example
        '400':
          description: >-
            Bad request - Invalid query parameters or body. See `details` for
            each failing field
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                      - invalid_request
                      - unauthorized
                      - forbidden
                      - plan_required
                      - not_found
                      - unsupported_media_type
                      - rate_limited
                      - internal_error
                      - upstream_unavailable
                    description: >-
                      A machine-readable code identifying the error. Use this
                      value for programmatic error handling.
                  message:
                    type: string
                    description: >-
                      A human-readable description. Wording may change; branch
                      on `code` instead.
                  request_id:
                    type: string
                    description: >-
                      The unique ID of this request, also returned as the
                      `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: >-
                            The parameter or body field that failed validation,
                            such as `limit`. Empty for errors that apply to the
                            whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                        - path
                        - message
                      additionalProperties: false
                required:
                  - status
                  - error
                  - code
                  - message
                  - request_id
                additionalProperties: false
                description: >-
                  Bad request - Invalid query parameters or body. See `details`
                  for each failing field
              example:
                status: 400
                error: Bad Request
                code: invalid_request
                message: The request is invalid.
                request_id: req-1
                details:
                  - path: limit
                    message: 'Too big: expected number to be <=50'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                      - invalid_request
                      - unauthorized
                      - forbidden
                      - plan_required
                      - not_found
                      - unsupported_media_type
                      - rate_limited
                      - internal_error
                      - upstream_unavailable
                    description: >-
                      A machine-readable code identifying the error. Use this
                      value for programmatic error handling.
                  message:
                    type: string
                    description: >-
                      A human-readable description. Wording may change; branch
                      on `code` instead.
                  request_id:
                    type: string
                    description: >-
                      The unique ID of this request, also returned as the
                      `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: >-
                            The parameter or body field that failed validation,
                            such as `limit`. Empty for errors that apply to the
                            whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                        - path
                        - message
                      additionalProperties: false
                required:
                  - status
                  - error
                  - code
                  - message
                  - request_id
                additionalProperties: false
                description: Unauthorized - Missing or invalid API key
              example:
                status: 401
                error: Unauthorized
                code: unauthorized
                message: Missing or invalid API key.
                request_id: req-1
        '403':
          description: >-
            Forbidden - Missing scope, insufficient permission, or the plan does
            not include this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                      - invalid_request
                      - unauthorized
                      - forbidden
                      - plan_required
                      - not_found
                      - unsupported_media_type
                      - rate_limited
                      - internal_error
                      - upstream_unavailable
                    description: >-
                      A machine-readable code identifying the error. Use this
                      value for programmatic error handling.
                  message:
                    type: string
                    description: >-
                      A human-readable description. Wording may change; branch
                      on `code` instead.
                  request_id:
                    type: string
                    description: >-
                      The unique ID of this request, also returned as the
                      `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: >-
                            The parameter or body field that failed validation,
                            such as `limit`. Empty for errors that apply to the
                            whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                        - path
                        - message
                      additionalProperties: false
                required:
                  - status
                  - error
                  - code
                  - message
                  - request_id
                additionalProperties: false
                description: >-
                  Forbidden - Missing scope, insufficient permission, or the
                  plan does not include this operation
              examples:
                example1:
                  value:
                    status: 403
                    error: Forbidden
                    code: forbidden
                    message: You do not have access to the requested resource.
                    request_id: req-1
                example2:
                  value:
                    status: 403
                    error: Forbidden
                    code: plan_required
                    message: >-
                      The API key owner must have a Blinq Pro or Business plan
                      to use this endpoint.
                    request_id: req-1
        '404':
          description: >-
            Not found - The workspace was not found, you are not its owner or
            admin, or access was denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                      - invalid_request
                      - unauthorized
                      - forbidden
                      - plan_required
                      - not_found
                      - unsupported_media_type
                      - rate_limited
                      - internal_error
                      - upstream_unavailable
                    description: >-
                      A machine-readable code identifying the error. Use this
                      value for programmatic error handling.
                  message:
                    type: string
                    description: >-
                      A human-readable description. Wording may change; branch
                      on `code` instead.
                  request_id:
                    type: string
                    description: >-
                      The unique ID of this request, also returned as the
                      `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: >-
                            The parameter or body field that failed validation,
                            such as `limit`. Empty for errors that apply to the
                            whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                        - path
                        - message
                      additionalProperties: false
                required:
                  - status
                  - error
                  - code
                  - message
                  - request_id
                additionalProperties: false
                description: >-
                  Not found - The workspace was not found, you are not its owner
                  or admin, or access was denied
              example:
                status: 404
                error: Not Found
                code: not_found
                message: The requested resource was not found.
                request_id: req-1
        '413':
          description: >-
            Payload too large - The request body exceeds the maximum allowed
            size
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                      - invalid_request
                      - unauthorized
                      - forbidden
                      - plan_required
                      - not_found
                      - unsupported_media_type
                      - rate_limited
                      - internal_error
                      - upstream_unavailable
                    description: >-
                      A machine-readable code identifying the error. Use this
                      value for programmatic error handling.
                  message:
                    type: string
                    description: >-
                      A human-readable description. Wording may change; branch
                      on `code` instead.
                  request_id:
                    type: string
                    description: >-
                      The unique ID of this request, also returned as the
                      `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: >-
                            The parameter or body field that failed validation,
                            such as `limit`. Empty for errors that apply to the
                            whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                        - path
                        - message
                      additionalProperties: false
                required:
                  - status
                  - error
                  - code
                  - message
                  - request_id
                additionalProperties: false
                description: >-
                  Payload too large - The request body exceeds the maximum
                  allowed size
              example:
                status: 413
                error: Payload Too Large
                code: invalid_request
                message: Request body is too large
                request_id: req-1
        '415':
          description: Unsupported media type - The request body must be `application/json`
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                      - invalid_request
                      - unauthorized
                      - forbidden
                      - plan_required
                      - not_found
                      - unsupported_media_type
                      - rate_limited
                      - internal_error
                      - upstream_unavailable
                    description: >-
                      A machine-readable code identifying the error. Use this
                      value for programmatic error handling.
                  message:
                    type: string
                    description: >-
                      A human-readable description. Wording may change; branch
                      on `code` instead.
                  request_id:
                    type: string
                    description: >-
                      The unique ID of this request, also returned as the
                      `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: >-
                            The parameter or body field that failed validation,
                            such as `limit`. Empty for errors that apply to the
                            whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                        - path
                        - message
                      additionalProperties: false
                required:
                  - status
                  - error
                  - code
                  - message
                  - request_id
                additionalProperties: false
                description: >-
                  Unsupported media type - The request body must be
                  `application/json`
              example:
                status: 415
                error: Unsupported Media Type
                code: unsupported_media_type
                message: 'Unsupported Media Type: text/plain'
                request_id: req-1
      security:
        - API key: []
components:
  securitySchemes:
    API key:
      type: http
      scheme: bearer
      description: >-
        Send a Blinq API key as `Authorization: Bearer <api-key>`; enter only
        the key in the documentation playground.


        Create and revoke keys in the Blinq web app under Settings > API keys.
        See Creating and revoking keys above.


        The key needs the scopes required by the operation, and public API
        access requires a Pro or Business plan.

````

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