openapi: 3.0.0
info:
  description: Socket webhooks API endpoints.
  title: Socket Webhooks API
  version: '0'
servers:
- url: https://api.socket.dev/v0
paths:
  /orgs/{org_slug}/webhooks:
    get:
      tags:
      - webhooks
      summary: List all webhooks
      externalDocs:
        description: Webhooks documentation
        url: https://docs.socket.dev/docs/webhooks
      operationId: getOrgWebhooksList
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: ''
        schema:
          type: string
          default: created_at
      - name: direction
        in: query
        required: false
        description: ''
        schema:
          type: string
          default: desc
      - name: per_page
        in: query
        required: false
        description: ''
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 30
      - name: page
        in: query
        required: false
        description: ''
        schema:
          type: integer
          minimum: 1
          default: 1
      security:
      - bearerAuth:
        - webhooks:list
      - basicAuth:
        - webhooks:list
      description: 'List all webhooks in the specified organization.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - webhooks:list'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      description: ''
                      properties:
                        id:
                          type: string
                          description: The ID of the webhook
                          default: ''
                        created_at:
                          type: string
                          description: The creation date of the webhook
                          default: ''
                        updated_at:
                          type: string
                          description: The last update date of the webhook
                          default: ''
                        name:
                          type: string
                          description: The name of the webhook
                          default: ''
                        description:
                          type: string
                          description: The description of the webhook
                          default: ''
                          nullable: true
                        url:
                          type: string
                          description: The URL where webhook events will be sent
                          default: ''
                        secret:
                          type: string
                          description: The signing key used to sign webhook payloads
                          default: ''
                          nullable: true
                        events:
                          type: array
                          items:
                            type: string
                            description: The event types to subscribe to
                            default: ''
                          description: Array of event names
                        headers:
                          type: object
                          description: Custom headers to include in webhook requests
                          default: null
                          nullable: true
                        filters:
                          type: object
                          additionalProperties: false
                          description: ''
                          properties:
                            repositoryIds:
                              type: array
                              items:
                                type: string
                                description: Repository IDs to filter events
                                default: ''
                              description: Array of repository IDs
                              nullable: true
                          required:
                          - repositoryIds
                          nullable: true
                      required:
                      - created_at
                      - description
                      - events
                      - filters
                      - headers
                      - id
                      - name
                      - secret
                      - updated_at
                      - url
                    description: ''
                  nextPage:
                    type: integer
                    description: ''
                    default: 0
                    nullable: true
                required:
                - nextPage
                - results
          description: List of webhooks
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
    post:
      tags:
      - webhooks
      summary: Create a webhook
      externalDocs:
        description: Webhooks documentation
        url: https://docs.socket.dev/docs/webhooks
      operationId: createOrgWebhook
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: The name of the webhook
                  default: ''
                url:
                  type: string
                  description: The URL where webhook events will be sent
                  default: ''
                secret:
                  type: string
                  description: The signing key used to sign webhook payloads
                  default: ''
                events:
                  type: array
                  items:
                    type: string
                    description: The event types to subscribe to
                    default: ''
                  description: Array of event names
                description:
                  type: string
                  description: The description of the webhook
                  default: ''
                  nullable: true
                headers:
                  type: object
                  description: Custom headers to include in webhook requests
                  default: null
                  nullable: true
                filters:
                  type: object
                  additionalProperties: false
                  description: ''
                  properties:
                    repositoryIds:
                      type: array
                      items:
                        type: string
                        description: Repository IDs to filter events
                        default: ''
                      description: Array of repository IDs
                      nullable: true
                  required:
                  - repositoryIds
                  nullable: true
              required:
              - events
              - name
              - secret
              - url
        required: false
      security:
      - bearerAuth:
        - webhooks:create
      - basicAuth:
        - webhooks:create
      description: 'Create a new webhook. Returns the created webhook details.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - webhooks:create'
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  id:
                    type: string
                    description: The ID of the webhook
                    default: ''
                  created_at:
                    type: string
                    description: The creation date of the webhook
                    default: ''
                  updated_at:
                    type: string
                    description: The last update date of the webhook
                    default: ''
                  name:
                    type: string
                    description: The name of the webhook
                    default: ''
                  description:
                    type: string
                    description: The description of the webhook
                    default: ''
                    nullable: true
                  url:
                    type: string
                    description: The URL where webhook events will be sent
                    default: ''
                  secret:
                    type: string
                    description: The signing key used to sign webhook payloads
                    default: ''
                    nullable: true
                  events:
                    type: array
                    items:
                      type: string
                      description: The event types to subscribe to
                      default: ''
                    description: Array of event names
                  headers:
                    type: object
                    description: Custom headers to include in webhook requests
                    default: null
                    nullable: true
                  filters:
                    type: object
                    additionalProperties: false
                    description: ''
                    properties:
                      repositoryIds:
                        type: array
                        items:
                          type: string
                          description: Repository IDs to filter events
                          default: ''
                        description: Array of repository IDs
                        nullable: true
                    required:
                    - repositoryIds
                    nullable: true
                required:
                - created_at
                - description
                - events
                - filters
                - headers
                - id
                - name
                - secret
                - updated_at
                - url
          description: The created webhook
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
  /orgs/{org_slug}/webhooks/{webhook_id}:
    get:
      tags:
      - webhooks
      summary: Get webhook
      externalDocs:
        description: Webhooks documentation
        url: https://docs.socket.dev/docs/webhooks
      operationId: getOrgWebhook
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: webhook_id
        in: path
        required: true
        description: The ID of the webhook
        schema:
          type: string
      security:
      - bearerAuth:
        - webhooks:list
      - basicAuth:
        - webhooks:list
      description: 'Get a webhook for the specified organization.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - webhooks:list'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  id:
                    type: string
                    description: The ID of the webhook
                    default: ''
                  created_at:
                    type: string
                    description: The creation date of the webhook
                    default: ''
                  updated_at:
                    type: string
                    description: The last update date of the webhook
                    default: ''
                  name:
                    type: string
                    description: The name of the webhook
                    default: ''
                  description:
                    type: string
                    description: The description of the webhook
                    default: ''
                    nullable: true
                  url:
                    type: string
                    description: The URL where webhook events will be sent
                    default: ''
                  secret:
                    type: string
                    description: The signing key used to sign webhook payloads
                    default: ''
                    nullable: true
                  events:
                    type: array
                    items:
                      type: string
                      description: The event types to subscribe to
                      default: ''
                    description: Array of event names
                  headers:
                    type: object
                    description: Custom headers to include in webhook requests
                    default: null
                    nullable: true
                  filters:
                    type: object
                    additionalProperties: false
                    description: ''
                    properties:
                      repositoryIds:
                        type: array
                        items:
                          type: string
                          description: Repository IDs to filter events
                          default: ''
                        description: Array of repository IDs
                        nullable: true
                    required:
                    - repositoryIds
                    nullable: true
                required:
                - created_at
                - description
                - events
                - filters
                - headers
                - id
                - name
                - secret
                - updated_at
                - url
          description: Webhook details
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
    put:
      tags:
      - webhooks
      summary: Update webhook
      externalDocs:
        description: Webhooks documentation
        url: https://docs.socket.dev/docs/webhooks
      operationId: updateOrgWebhook
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: webhook_id
        in: path
        required: true
        description: The ID of the webhook
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: The name of the webhook
                  default: ''
                description:
                  type: string
                  description: The description of the webhook
                  default: ''
                  nullable: true
                url:
                  type: string
                  description: The URL where webhook events will be sent
                  default: ''
                secret:
                  type: string
                  description: The signing key used to sign webhook payloads
                  default: ''
                  nullable: true
                events:
                  type: array
                  items:
                    type: string
                    description: The event types to subscribe to
                    default: ''
                  description: Array of event names
                headers:
                  type: object
                  description: Custom headers to include in webhook requests
                  default: null
                  nullable: true
                filters:
                  type: object
                  additionalProperties: false
                  description: ''
                  properties:
                    repositoryIds:
                      type: array
                      items:
                        type: string
                        description: Repository IDs to filter events
                        default: ''
                      description: Array of repository IDs
                      nullable: true
                  required:
                  - repositoryIds
                  nullable: true
              description: ''
        required: false
      security:
      - bearerAuth:
        - webhooks:update
      - basicAuth:
        - webhooks:update
      description: 'Update details of an existing webhook.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - webhooks:update'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  id:
                    type: string
                    description: The ID of the webhook
                    default: ''
                  created_at:
                    type: string
                    description: The creation date of the webhook
                    default: ''
                  updated_at:
                    type: string
                    description: The last update date of the webhook
                    default: ''
                  name:
                    type: string
                    description: The name of the webhook
                    default: ''
                  description:
                    type: string
                    description: The description of the webhook
                    default: ''
                    nullable: true
                  url:
                    type: string
                    description: The URL where webhook events will be sent
                    default: ''
                  secret:
                    type: string
                    description: The signing key used to sign webhook payloads
                    default: ''
                    nullable: true
                  events:
                    type: array
                    items:
                      type: string
                      description: The event types to subscribe to
                      default: ''
                    description: Array of event names
                  headers:
                    type: object
                    description: Custom headers to include in webhook requests
                    default: null
                    nullable: true
                  filters:
                    type: object
                    additionalProperties: false
                    description: ''
                    properties:
                      repositoryIds:
                        type: array
                        items:
                          type: string
                          description: Repository IDs to filter events
                          default: ''
                        description: Array of repository IDs
                        nullable: true
                    required:
                    - repositoryIds
                    nullable: true
                required:
                - created_at
                - description
                - events
                - filters
                - headers
                - id
                - name
                - secret
                - updated_at
                - url
          description: Updated webhook details
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
    delete:
      tags:
      - webhooks
      summary: Delete webhook
      externalDocs:
        description: Webhooks documentation
        url: https://docs.socket.dev/docs/webhooks
      operationId: deleteOrgWebhook
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: webhook_id
        in: path
        required: true
        description: The ID of the webhook
        schema:
          type: string
      security:
      - bearerAuth:
        - webhooks:delete
      - basicAuth:
        - webhooks:delete
      description: 'Delete a webhook. This will stop all future webhook deliveries to the webhook URL.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - webhooks:delete'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  status:
                    type: string
                    description: ''
                    default: ok
                required:
                - status
          description: Success
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
components:
  requestBodies: {}
  responses:
    SocketBadRequest:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Bad request
    SocketUnauthorized:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Unauthorized
    SocketForbidden:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Insufficient max_quota for API method
    SocketNotFoundResponse:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Resource not found
    SocketTooManyRequestsResponse:
      description: Insufficient quota for API route
      headers:
        Retry-After:
          description: 'Retry contacting the endpoint *at least* after seconds.

            See https://tools.ietf.org/html/rfc7231#section-7.1.3'
          schema:
            format: int32
            type: integer
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
    SocketInternalServerError:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Internal server error
    SocketConflict:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Resource already exists
    SocketGone:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Gone
  schemas: {}
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Organization Tokens can be passed as a Bearer token
    basicAuth:
      type: http
      scheme: basic
      description: Organization Tokens can be passed as the user field in basic auth