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.
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