Logo.dev Webhook endpoints API

openapi: 3.2.0
info:
  title: Logo.dev Webhook endpoints API
  description: 'Logo.dev serves brand assets from two hosts, each with its own key:


    - **Logo.dev CDN** (`img.logo.dev`) returns a logo image. Authenticate with a **publishable key** in the `token` query parameter. It is safe in client-side code.

    - **Logo.dev API** (`api.logo.dev`) returns JSON. Authenticate with a **secret key** in the `Authorization: Bearer` header. Call it only from your server.


    Get your keys from the dashboard.'
  version: 2.0.0
  contact:
    name: Logo.dev Support
    email: support@logo.dev
    url: https://docs.logo.dev
servers:
- url: https://api.logo.dev
  description: REST APIs (Brand Search, Brand Data)
tags:
- name: Webhook Endpoints
  description: Manage the URLs that receive webhook events.
paths:
  /v2/webhook_endpoints:
    post:
      tags:
      - Webhook Endpoints
      summary: Create a webhook endpoint
      description: Registers a URL to receive webhook events. Needs a paid plan and the owner or admin role. See Who can use webhooks.
      operationId: v2CreateWebhookEndpoint
      x-mint:
        metadata:
          description: Register a URL to receive brand webhook events.
        content: "<Card title=\"Get your API keys\" icon=\"key\" href=\"https://www.logo.dev/dashboard/api-keys\" horizontal arrow>\n  Your dashboard has a publishable key for the Logo.dev CDN and a secret key for the Logo.dev API. Every plan includes both.\n</Card>"
      security:
      - secretKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/V2WebhookEndpointInput'
              required:
              - url
            example:
              url: https://hooks.example.com/logo-dev
              description: Production
              filter_types:
              - brand.updated
      responses:
        '201':
          description: The endpoint was created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/V2WebhookEndpoint'
                  metadata:
                    $ref: '#/components/schemas/V2Metadata'
                required:
                - data
                - metadata
              example:
                data:
                  object: webhook_endpoint
                  id: ep_2mX9kL4pQ7rT1vW3yZ5aB8cD0e
                  url: https://hooks.example.com/logo-dev
                  description: Production
                  disabled: false
                  filter_types:
                  - brand.updated
                  created_at: '2026-09-21T12:00:00Z'
                  updated_at: '2026-09-21T12:00:00Z'
                metadata:
                  request_id: request_01k6z8m2a4b5c6d7e8f9g0h1j2
        '400':
          description: 'The body is invalid: a blank `url`, an unknown event type, or malformed JSON.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: invalid_request
                  message: 'unknown event type ''brand.deleted'': must be one of brand.updated, brand.indexed: bad format'
                docs_url: https://www.logo.dev/docs/platform/errors
        '401':
          $ref: '#/components/responses/V2Unauthorized'
        '403':
          $ref: '#/components/responses/V2WebhooksNotEnabled'
        '409':
          $ref: '#/components/responses/V2LimitExceeded'
        '500':
          description: Managing the endpoint failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: internal
                  message: failed to manage webhook endpoint
                docs_url: https://www.logo.dev/docs/platform/errors
    get:
      tags:
      - Webhook Endpoints
      summary: List webhook endpoints
      description: Returns every webhook endpoint on your team. Not paginated. Needs a paid plan. See Who can use webhooks.
      operationId: v2ListWebhookEndpoints
      x-mint:
        metadata:
          description: List your team's webhook endpoints.
        content: "<Card title=\"Get your API keys\" icon=\"key\" href=\"https://www.logo.dev/dashboard/api-keys\" horizontal arrow>\n  Your dashboard has a publishable key for the Logo.dev CDN and a secret key for the Logo.dev API. Every plan includes both.\n</Card>"
      security:
      - secretKey: []
      responses:
        '200':
          description: All endpoints. An empty array when there are none.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/V2WebhookEndpoint'
                  metadata:
                    $ref: '#/components/schemas/V2Metadata'
                required:
                - data
                - metadata
              example:
                data:
                - object: webhook_endpoint
                  id: ep_2mX9kL4pQ7rT1vW3yZ5aB8cD0e
                  url: https://hooks.example.com/logo-dev
                  description: Production
                  disabled: false
                  filter_types:
                  - brand.updated
                  created_at: '2026-09-21T12:00:00Z'
                  updated_at: '2026-09-21T12:00:00Z'
                metadata:
                  request_id: request_01k6z8m2a4b5c6d7e8f9g0h1j2
        '401':
          $ref: '#/components/responses/V2Unauthorized'
        '403':
          $ref: '#/components/responses/V2WebhooksNotEnabled'
        '500':
          description: Managing the endpoint failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: internal
                  message: failed to manage webhook endpoint
                docs_url: https://www.logo.dev/docs/platform/errors
  /v2/webhook_endpoints/{id}:
    get:
      tags:
      - Webhook Endpoints
      summary: Get a webhook endpoint
      description: Returns one webhook endpoint. Needs a paid plan. See Who can use webhooks.
      operationId: v2GetWebhookEndpoint
      x-mint:
        metadata:
          description: Get one webhook endpoint.
        content: "<Card title=\"Get your API keys\" icon=\"key\" href=\"https://www.logo.dev/dashboard/api-keys\" horizontal arrow>\n  Your dashboard has a publishable key for the Logo.dev CDN and a secret key for the Logo.dev API. Every plan includes both.\n</Card>"
      security:
      - secretKey: []
      parameters:
      - $ref: '#/components/parameters/V2EndpointIdPath'
      responses:
        '200':
          description: The endpoint.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/V2WebhookEndpoint'
                  metadata:
                    $ref: '#/components/schemas/V2Metadata'
                required:
                - data
                - metadata
              example:
                data:
                  object: webhook_endpoint
                  id: ep_2mX9kL4pQ7rT1vW3yZ5aB8cD0e
                  url: https://hooks.example.com/logo-dev
                  description: Production
                  disabled: false
                  filter_types:
                  - brand.updated
                  created_at: '2026-09-21T12:00:00Z'
                  updated_at: '2026-09-21T12:00:00Z'
                metadata:
                  request_id: request_01k6z8m2a4b5c6d7e8f9g0h1j2
        '401':
          $ref: '#/components/responses/V2Unauthorized'
        '403':
          $ref: '#/components/responses/V2WebhooksNotEnabled'
        '404':
          description: No webhook endpoint has this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: resource_missing
                  message: no webhook endpoint with this id
                  target: id
                docs_url: https://www.logo.dev/docs/platform/errors
        '500':
          description: Managing the endpoint failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: internal
                  message: failed to manage webhook endpoint
                docs_url: https://www.logo.dev/docs/platform/errors
    patch:
      tags:
      - Webhook Endpoints
      summary: Update a webhook endpoint
      description: 'Changes an endpoint. Send only the fields to change; omitted fields keep their value. Send `filter_types: []` to receive every event type. Needs a paid plan and the owner or admin role. See Who can use webhooks.'
      operationId: v2UpdateWebhookEndpoint
      x-mint:
        metadata:
          description: Change a webhook endpoint's URL, description, event types, or disabled state.
        content: "<Card title=\"Get your API keys\" icon=\"key\" href=\"https://www.logo.dev/dashboard/api-keys\" horizontal arrow>\n  Your dashboard has a publishable key for the Logo.dev CDN and a secret key for the Logo.dev API. Every plan includes both.\n</Card>"
      security:
      - secretKey: []
      parameters:
      - $ref: '#/components/parameters/V2EndpointIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/V2WebhookEndpointInput'
            example:
              url: https://hooks.example.com/logo-dev
              description: Production
              filter_types:
              - brand.updated
      responses:
        '200':
          description: The updated endpoint.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/V2WebhookEndpoint'
                  metadata:
                    $ref: '#/components/schemas/V2Metadata'
                required:
                - data
                - metadata
              example:
                data:
                  object: webhook_endpoint
                  id: ep_2mX9kL4pQ7rT1vW3yZ5aB8cD0e
                  url: https://hooks.example.com/logo-dev
                  description: Production
                  disabled: false
                  filter_types:
                  - brand.updated
                  created_at: '2026-09-21T12:00:00Z'
                  updated_at: '2026-09-21T12:00:00Z'
                metadata:
                  request_id: request_01k6z8m2a4b5c6d7e8f9g0h1j2
        '400':
          description: 'The body is invalid: a blank `url`, an unknown event type, or malformed JSON.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: invalid_request
                  message: 'unknown event type ''brand.deleted'': must be one of brand.updated, brand.indexed: bad format'
                docs_url: https://www.logo.dev/docs/platform/errors
        '401':
          $ref: '#/components/responses/V2Unauthorized'
        '403':
          $ref: '#/components/responses/V2WebhooksNotEnabled'
        '404':
          description: No webhook endpoint has this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: resource_missing
                  message: no webhook endpoint with this id
                  target: id
                docs_url: https://www.logo.dev/docs/platform/errors
        '500':
          description: Managing the endpoint failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: internal
                  message: failed to manage webhook endpoint
                docs_url: https://www.logo.dev/docs/platform/errors
    delete:
      tags:
      - Webhook Endpoints
      summary: Delete a webhook endpoint
      description: Deletes an endpoint. Deliveries to it stop. Needs a paid plan and the owner or admin role. See Who can use webhooks.
      operationId: v2DeleteWebhookEndpoint
      x-mint:
        metadata:
          description: Delete a webhook endpoint.
        content: "<Card title=\"Get your API keys\" icon=\"key\" href=\"https://www.logo.dev/dashboard/api-keys\" horizontal arrow>\n  Your dashboard has a publishable key for the Logo.dev CDN and a secret key for the Logo.dev API. Every plan includes both.\n</Card>"
      security:
      - secretKey: []
      parameters:
      - $ref: '#/components/parameters/V2EndpointIdPath'
      responses:
        '204':
          description: Deleted. No body.
        '401':
          $ref: '#/components/responses/V2Unauthorized'
        '403':
          $ref: '#/components/responses/V2WebhooksNotEnabled'
        '404':
          description: No webhook endpoint has this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: resource_missing
                  message: no webhook endpoint with this id
                  target: id
                docs_url: https://www.logo.dev/docs/platform/errors
        '500':
          description: Managing the endpoint failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: internal
                  message: failed to manage webhook endpoint
                docs_url: https://www.logo.dev/docs/platform/errors
  /v2/webhook_endpoints/{id}/secret:
    get:
      tags:
      - Webhook Endpoints
      summary: Get a webhook signing secret
      description: Returns the endpoint's signing secret, used to verify deliveries. Any team member can read it. Needs a paid plan. See Who can use webhooks.
      operationId: v2GetWebhookEndpointSecret
      x-mint:
        metadata:
          description: Read a webhook endpoint's signing secret.
        content: "<Card title=\"Get your API keys\" icon=\"key\" href=\"https://www.logo.dev/dashboard/api-keys\" horizontal arrow>\n  Your dashboard has a publishable key for the Logo.dev CDN and a secret key for the Logo.dev API. Every plan includes both.\n</Card>"
      security:
      - secretKey: []
      parameters:
      - $ref: '#/components/parameters/V2EndpointIdPath'
      responses:
        '200':
          description: The current secret.
          headers:
            Cache-Control:
              description: Always `no-store`.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/V2WebhookEndpointSecret'
                  metadata:
                    $ref: '#/components/schemas/V2Metadata'
                required:
                - data
                - metadata
              example:
                data:
                  object: webhook_endpoint_secret
                  key: WEBHOOK_SIGNING_SECRET
                metadata:
                  request_id: request_01k6z8m2a4b5c6d7e8f9g0h1j2
        '401':
          $ref: '#/components/responses/V2Unauthorized'
        '403':
          $ref: '#/components/responses/V2WebhooksNotEnabled'
        '404':
          description: No webhook endpoint has this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: resource_missing
                  message: no webhook endpoint with this id
                  target: id
                docs_url: https://www.logo.dev/docs/platform/errors
        '500':
          description: Managing the endpoint failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: internal
                  message: failed to manage webhook endpoint
                docs_url: https://www.logo.dev/docs/platform/errors
    post:
      tags:
      - Webhook Endpoints
      summary: Rotate a webhook signing secret
      description: Replaces the endpoint's signing secret and returns the new one. Update your verification code with it. Needs a paid plan and the owner or admin role. See Who can use webhooks.
      operationId: v2RotateWebhookEndpointSecret
      x-mint:
        metadata:
          description: Replace a webhook endpoint's signing secret.
        content: "<Card title=\"Get your API keys\" icon=\"key\" href=\"https://www.logo.dev/dashboard/api-keys\" horizontal arrow>\n  Your dashboard has a publishable key for the Logo.dev CDN and a secret key for the Logo.dev API. Every plan includes both.\n</Card>"
      security:
      - secretKey: []
      parameters:
      - $ref: '#/components/parameters/V2EndpointIdPath'
      responses:
        '200':
          description: The new secret.
          headers:
            Cache-Control:
              description: Always `no-store`.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/V2WebhookEndpointSecret'
                  metadata:
                    $ref: '#/components/schemas/V2Metadata'
                required:
                - data
                - metadata
              example:
                data:
                  object: webhook_endpoint_secret
                  key: WEBHOOK_SIGNING_SECRET
                metadata:
                  request_id: request_01k6z8m2a4b5c6d7e8f9g0h1j2
        '401':
          $ref: '#/components/responses/V2Unauthorized'
        '403':
          $ref: '#/components/responses/V2WebhooksNotEnabled'
        '404':
          description: No webhook endpoint has this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: resource_missing
                  message: no webhook endpoint with this id
                  target: id
                docs_url: https://www.logo.dev/docs/platform/errors
        '500':
          description: Managing the endpoint failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
              example:
                error:
                  code: internal
                  message: failed to manage webhook endpoint
                docs_url: https://www.logo.dev/docs/platform/errors
components:
  schemas:
    V2WebhookEndpointSecret:
      type: object
      properties:
        object:
          type: string
          const: webhook_endpoint_secret
        key:
          type: string
          description: The endpoint's signing secret. Use it to verify that deliveries come from Logo.dev.
      required:
      - object
      - key
    V2WebhookEndpointInput:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: Where deliveries are sent.
        description:
          type: string
        filter_types:
          type: array
          items:
            type: string
            enum:
            - brand.updated
            - brand.indexed
          description: Event types to receive. Omit or send `[]` for all of them.
        disabled:
          type: boolean
          description: Send `true` to create or keep the endpoint switched off.
    V2Resolution:
      type: object
      description: How the request identified the brand.
      properties:
        type:
          type: string
          enum:
          - domain
          - ticker
          - isin
          - crypto
          - name
          - brand_id
          description: Which identifier the request used.
        value:
          type: string
          description: 'The identifier after normalization: the registrable domain, an upper-cased ticker, and so on.'
        method:
          type: string
          enum:
          - direct
          - domain
          - security
          - crypto
          - search
          - ''
          description: How the identifier reached the brand. `direct` is a brand id or a domain that is its own brand; `domain` went through an alias or redirect; `security` is a ticker or ISIN; `crypto` is a crypto token symbol; `search` is a name lookup. Empty on a cached miss.
        context:
          type: object
          description: Reserved for brands involved in a merchant lookup. Always `{}` today.
      required:
      - type
      - value
      - method
      - context
    V2Metadata:
      type: object
      properties:
        request_id:
          type: string
          description: Unique id for this request. Also sent as the `Request-Id` header.
          examples:
          - request_01k6z8m2a4b5c6d7e8f9g0h1j2
        resolution:
          allOf:
          - $ref: '#/components/schemas/V2Resolution'
          description: Brand and image lookups only.
        pending:
          allOf:
          - $ref: '#/components/schemas/V2Pending'
          description: '`202` responses only.'
        subscription:
          type: object
          description: 'Present when a brand lookup (`GET /v2/brands` or `GET /v2/brands/{id}`) ran the automatic subscribe: webhooks are on for the account, and `nosubscribe` is not `true`. See [automatic subscriptions](/brand/introduction#automatic-subscriptions).'
          properties:
            status:
              type: string
              enum:
              - subscribed
              - quota_exceeded
              description: '`subscribed`: the account is subscribed to the brand. `quota_exceeded`: the account is at its plan''s subscription limit, so the brand was not subscribed. The lookup is answered and billed either way.'
            message:
              type: string
              description: Why the subscribe was refused. Only with `quota_exceeded`.
          required:
          - status
      required:
      - request_id
    V2Pending:
      type: object
      description: Present only on a `202`. Tells you when to retry.
      properties:
        reason:
          type: string
          enum:
          - indexing
          - resolving
          description: '`indexing` is a brand''s first crawl; `resolving` means the identifier is still being matched to a brand.'
        message:
          type: string
        retry_after_seconds:
          type: integer
          description: Wait this long before retrying. Matches the `Retry-After` header.
          examples:
          - 30
        expires_in_seconds:
          type: integer
          description: Stop polling after this long.
          examples:
          - 300
        webhook:
          type: boolean
          description: Whether a `brand.indexed` webhook event carrying this request's `request_id` will be sent when the lookup settles.
        doc_url:
          type: string
          format: uri
      required:
      - reason
      - message
      - retry_after_seconds
      - expires_in_seconds
      - webhook
      - doc_url
    V2AuthError:
      type: object
      description: Returned when the secret key is missing, malformed, unknown, or disabled, before the request reaches the v2 route.
      properties:
        msg:
          type: string
        docs_url:
          type: string
          format: uri
      required:
      - msg
    V2Error:
      type: object
      description: Error envelope for v2 routes.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - invalid_request
              - unauthorized
              - forbidden
              - resource_missing
              - insufficient_credits
              - rate_limited
              - limit_exceeded
              - internal
            message:
              type: string
            target:
              type: string
              description: The parameter at fault, when there is exactly one.
          required:
          - code
          - message
        docs_url:
          type: string
          format: uri
          description: Documentation for this class of error.
      required:
      - error
    V2WebhookEndpoint:
      type: object
      properties:
        object:
          type: string
          const: webhook_endpoint
        id:
          type: string
          examples:
          - ep_2mX9kL4pQ7rT1vW3yZ5aB8cD0e
        url:
          type: string
          format: uri
        description:
          type: string
          description: Empty string when unset.
        disabled:
          type: boolean
          description: '`true` when you switched the endpoint off, or when deliveries were stopped after sustained failures.'
        filter_types:
          type: array
          items:
            type: string
            enum:
            - brand.updated
            - brand.indexed
          description: Event types this endpoint receives. An empty array means all of them.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - object
      - id
      - url
      - description
      - disabled
      - filter_types
      - created_at
      - updated_at
  responses:
    V2WebhooksNotEnabled:
      description: Your plan does not include webhooks, or your role cannot change them. See [Who can use webhooks](/webhooks#who-can-use-webhooks).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2Error'
          example:
            error:
              code: forbidden
              message: organization admin role required to change webhooks
            docs_url: https://www.logo.dev/docs/platform/errors
    V2LimitExceeded:
      description: Your account is at its plan's limit for this resource. Delete one, or upgrade. See [plan limits](/webhooks#plan-limits).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V2Error'
          examples:
            subscriptions:
              value:
                error:
                  code: limit_exceeded
                  message: 'brand subscription limit reached. the pro plan allows {limit} subscriptions: limit exceeded'
                docs_url: https://www.logo.dev/docs/platform/errors
            webhook_endpoints:
              value:
                error:
                  code: limit_exceeded
                  message: 'webhook endpoint limit reached. the pro plan allows {limit} endpoints: limit exceeded'
                docs_url: https://www.logo.dev/docs/platform/errors
    V2Unauthorized:
      description: The secret key is missing, malformed, unknown, or disabled. A publishable key (`pk_`) is refused.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/V2AuthError'
            - $ref: '#/components/schemas/V2Error'
          example:
            msg: invalid api token. make sure to use your secret key.
            docs_url: https://www.logo.dev/docs/platform/api-keys
  parameters:
    V2EndpointIdPath:
      name: id
      in: path
      required: true
      description: A webhook endpoint id.
      schema:
        type: string
        examples:
        - ep_2mX9kL4pQ7rT1vW3yZ5aB8cD0e
  securitySchemes:
    publishableKey:
      type: apiKey
      in: query
      name: token
      description: Your publishable key (`pk_`). Safe in client-side code. Works only with the Logo.dev CDN.
    secretKey:
      type: http
      scheme: bearer
      description: Your secret key (`sk_`), as `Bearer sk_...`. Call the Logo.dev API only from your server.
    transactionBetaKey:
      type: http
      scheme: bearer
      bearerFormat: tx_beta_…
      description: Transaction-only beta key, issued with your beta access and always visible in the Transaction Playground. Existing Logo.dev secret keys do not authenticate this beta.