Socket

Socket Webhooks API

Register, list, update, and delete webhooks that fire when scans complete, alerts trigger, triage decisions are made, or threat-feed entries match an organization's packages. Useful for connecting Socket to Slack, Jira, PagerDuty, or custom internal automation.

Socket Webhooks API is one of 15 APIs that Socket publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.

Tagged areas include Webhooks, Events, and Notifications. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 1 Naftiko capability spec.

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.socket.dev/reference/listorgwebhooks

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/socket-dev/refs/heads/main/openapi/socket-webhooks-api-openapi.yml

Other Resources

🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/socket-dev/refs/heads/main/capabilities/webhooks-webhooks.yaml

OpenAPI Specification

socket-webhooks-api-openapi.yml Raw ↑ 
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