WorkOS webhooks API

openapi: 3.1.1
info:
  title: WorkOS admin-portal webhooks API
  description: WorkOS REST API
  version: '1.0'
  contact:
    name: WorkOS
    url: https://workos.com
    email: support@workos.com
  license:
    name: MIT
    url: https://opensource.org/license/MIT
servers:
- url: https://api.workos.com
  description: Production
- url: https://api.workos-test.com
  description: Staging
security:
- bearer: []
tags:
- name: webhooks
  description: Manage webhooks.
  x-displayName: Webhooks
paths:
  /webhook_endpoints:
    get:
      description: Get a list of all of your existing webhook endpoints.
      operationId: WebhookEndpointsController_list
      parameters:
      - name: before
        required: false
        in: query
        description: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`.
        schema:
          example: xxx_01HXYZ123456789ABCDEFGHIJ
          type: string
      - name: after
        required: false
        in: query
        description: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`.
        schema:
          example: xxx_01HXYZ987654321KJIHGFEDCBA
          type: string
      - name: limit
        required: false
        in: query
        description: Upper limit on the number of objects to return, between `1` and `100`.
        schema:
          minimum: 1
          maximum: 100
          default: 10
          example: 10
          type: integer
      - name: order
        required: false
        in: query
        description: Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). Defaults to descending.
        schema:
          $ref: '#/components/schemas/PaginationOrder'
      responses:
        '200':
          description: List of webhook endpoints.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointList'
      summary: List Webhook Endpoints
      tags:
      - webhooks
    post:
      description: Create a new webhook endpoint to receive event notifications.
      operationId: WebhookEndpointsController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookEndpointDto'
      responses:
        '201':
          description: Webhook endpoint created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointJson'
        '409':
          description: A Webhook Endpoint with the same endpoint URL already exists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: The error code identifying the type of error.
                    example: duplicate_endpoint
                    const: duplicate_endpoint
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: Request could not be processed.
                required:
                - code
                - message
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  properties:
                    code:
                      type: string
                      description: The error code identifying the type of error.
                      example: invalid_url
                      const: invalid_url
                    message:
                      type: string
                      description: A human-readable description of the error.
                      example: Request could not be processed.
                  required:
                  - code
                  - message
                - type: object
                  properties:
                    code:
                      type: string
                      description: The error code identifying the type of error.
                      example: invalid_request_parameters
                      const: invalid_request_parameters
                    message:
                      type: string
                      description: A human-readable description of the error.
                      example: Validation failed.
                    errors:
                      type: array
                      items:
                        type: object
                        properties:
                          code:
                            type: string
                            description: The validation error code.
                            example: unknown_event_type
                          message:
                            type: string
                            description: A human-readable description of the validation error.
                            example: Invalid enum value.
                        required:
                        - code
                        - message
                      description: The list of validation errors.
                  required:
                  - code
                  - message
                  - errors
      summary: Create a Webhook Endpoint
      tags:
      - webhooks
  /webhook_endpoints/{id}:
    patch:
      description: Update the properties of an existing webhook endpoint.
      operationId: WebhookEndpointsController_update
      parameters:
      - name: id
        required: true
        in: path
        description: Unique identifier of the Webhook Endpoint.
        schema:
          type: string
          example: we_0123456789
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookEndpointDto'
      responses:
        '200':
          description: Webhook endpoint updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointJson'
        '404':
          description: Webhook endpoint not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: The error code identifying the type of error.
                    example: entity_not_found
                    const: entity_not_found
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: Request could not be processed.
                required:
                - code
                - message
        '409':
          description: A Webhook Endpoint with the same endpoint URL already exists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: The error code identifying the type of error.
                    example: duplicate_endpoint
                    const: duplicate_endpoint
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: Request could not be processed.
                required:
                - code
                - message
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  properties:
                    code:
                      type: string
                      description: The error code identifying the type of error.
                      example: invalid_url
                      const: invalid_url
                    message:
                      type: string
                      description: A human-readable description of the error.
                      example: Request could not be processed.
                  required:
                  - code
                  - message
                - type: object
                  properties:
                    code:
                      type: string
                      description: The error code identifying the type of error.
                      example: invalid_request_parameters
                      const: invalid_request_parameters
                    message:
                      type: string
                      description: A human-readable description of the error.
                      example: Validation failed.
                    errors:
                      type: array
                      items:
                        type: object
                        properties:
                          code:
                            type: string
                            description: The validation error code.
                            example: unknown_event_type
                          message:
                            type: string
                            description: A human-readable description of the validation error.
                            example: Invalid enum value.
                        required:
                        - code
                        - message
                      description: The list of validation errors.
                  required:
                  - code
                  - message
                  - errors
      summary: Update a Webhook Endpoint
      tags:
      - webhooks
    delete:
      description: Delete an existing webhook endpoint.
      operationId: WebhookEndpointsController_delete
      parameters:
      - name: id
        required: true
        in: path
        description: Unique identifier of the Webhook Endpoint.
        schema:
          type: string
          example: we_0123456789
      responses:
        '204':
          description: Webhook endpoint deleted successfully.
        '404':
          description: Webhook endpoint not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: The error code identifying the type of error.
                    example: entity_not_found
                    const: entity_not_found
                  message:
                    type: string
                    description: A human-readable description of the error.
                    example: Request could not be processed.
                required:
                - code
                - message
      summary: Delete a Webhook Endpoint
      tags:
      - webhooks
components:
  schemas:
    PaginationOrder:
      type: string
      enum:
      - normal
      - desc
      - asc
      example: desc
      default: desc
    WebhookEndpointList:
      type: object
      properties:
        object:
          type: string
          description: Indicates this is a list response.
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEndpointJson'
          description: The list of records for the current page.
        list_metadata:
          type: object
          properties:
            before:
              type:
              - string
              - 'null'
              description: An object ID that defines your place in the list. When the ID is not present, you are at the start of the list.
              example: we_01HXYZ123456789ABCDEFGHIJ
            after:
              type:
              - string
              - 'null'
              description: An object ID that defines your place in the list. When the ID is not present, you are at the end of the list.
              example: we_01HXYZ987654321KJIHGFEDCBA
          required:
          - before
          - after
          description: Pagination cursors for navigating between pages of results.
      required:
      - object
      - data
      - list_metadata
    UpdateWebhookEndpointDto:
      type: object
      properties:
        endpoint_url:
          type: string
          description: The HTTPS URL where webhooks will be sent.
          example: https://example.com/webhooks
        status:
          type: string
          enum:
          - enabled
          - disabled
          description: Whether the Webhook Endpoint is enabled or disabled.
          example: enabled
        events:
          type: array
          description: The events that the Webhook Endpoint is subscribed to.
          items:
            type: string
            enum:
            - authentication.email_verification_succeeded
            - authentication.magic_auth_failed
            - authentication.magic_auth_succeeded
            - authentication.mfa_succeeded
            - authentication.oauth_failed
            - authentication.oauth_succeeded
            - authentication.password_failed
            - authentication.password_succeeded
            - authentication.passkey_failed
            - authentication.passkey_succeeded
            - authentication.sso_failed
            - authentication.sso_started
            - authentication.sso_succeeded
            - authentication.sso_timed_out
            - authentication.radar_risk_detected
            - api_key.created
            - api_key.revoked
            - connection.activated
            - connection.deactivated
            - connection.saml_certificate_renewal_required
            - connection.saml_certificate_renewed
            - connection.deleted
            - dsync.activated
            - dsync.deleted
            - dsync.group.created
            - dsync.group.deleted
            - dsync.group.updated
            - dsync.group.user_added
            - dsync.group.user_removed
            - dsync.user.created
            - dsync.user.deleted
            - dsync.user.updated
            - email_verification.created
            - group.created
            - group.deleted
            - group.member_added
            - group.member_removed
            - group.updated
            - flag.created
            - flag.deleted
            - flag.updated
            - flag.rule_updated
            - invitation.accepted
            - invitation.created
            - invitation.resent
            - invitation.revoked
            - magic_auth.created
            - organization.created
            - organization.deleted
            - organization.updated
            - organization_domain.created
            - organization_domain.deleted
            - organization_domain.updated
            - organization_domain.verified
            - organization_domain.verification_failed
            - password_reset.created
            - password_reset.succeeded
            - user.created
            - user.updated
            - user.deleted
            - organization_membership.created
            - organization_membership.deleted
            - organization_membership.updated
            - role.created
            - role.deleted
            - role.updated
            - organization_role.created
            - organization_role.deleted
            - organization_role.updated
            - permission.created
            - permission.deleted
            - permission.updated
            - session.created
            - session.revoked
            - waitlist_user.approved
            - waitlist_user.created
            - waitlist_user.denied
          example:
          - user.created
          - dsync.user.created
    WebhookEndpointJson:
      type: object
      properties:
        object:
          type: string
          description: Distinguishes the Webhook Endpoint object.
          const: webhook_endpoint
        id:
          type: string
          description: Unique identifier of the Webhook Endpoint.
          example: we_0123456789
        endpoint_url:
          type: string
          description: The URL to which webhooks are sent.
          example: https://example.com/webhooks
        secret:
          type: string
          description: The secret used to sign webhook payloads.
          example: whsec_0FWAiVGkEfGBqqsJH4aNAGBJ4
        status:
          type: string
          enum:
          - enabled
          - disabled
          description: Whether the Webhook Endpoint is enabled or disabled.
          example: enabled
        events:
          type: array
          items:
            type: string
          description: The events that the Webhook Endpoint is subscribed to.
          example:
          - user.created
          - dsync.user.created
        created_at:
          format: date-time
          type: string
          description: An ISO 8601 timestamp.
          example: '2026-01-15T12:00:00.000Z'
        updated_at:
          format: date-time
          type: string
          description: An ISO 8601 timestamp.
          example: '2026-01-15T12:00:00.000Z'
      required:
      - object
      - id
      - endpoint_url
      - secret
      - status
      - events
      - created_at
      - updated_at
    CreateWebhookEndpointDto:
      type: object
      properties:
        endpoint_url:
          type: string
          description: The HTTPS URL where webhooks will be sent.
          example: https://example.com/webhooks
        events:
          type: array
          description: The events that the Webhook Endpoint is subscribed to.
          items:
            type: string
            enum:
            - authentication.email_verification_succeeded
            - authentication.magic_auth_failed
            - authentication.magic_auth_succeeded
            - authentication.mfa_succeeded
            - authentication.oauth_failed
            - authentication.oauth_succeeded
            - authentication.password_failed
            - authentication.password_succeeded
            - authentication.passkey_failed
            - authentication.passkey_succeeded
            - authentication.sso_failed
            - authentication.sso_started
            - authentication.sso_succeeded
            - authentication.sso_timed_out
            - authentication.radar_risk_detected
            - api_key.created
            - api_key.revoked
            - connection.activated
            - connection.deactivated
            - connection.saml_certificate_renewal_required
            - connection.saml_certificate_renewed
            - connection.deleted
            - dsync.activated
            - dsync.deleted
            - dsync.group.created
            - dsync.group.deleted
            - dsync.group.updated
            - dsync.group.user_added
            - dsync.group.user_removed
            - dsync.user.created
            - dsync.user.deleted
            - dsync.user.updated
            - email_verification.created
            - group.created
            - group.deleted
            - group.member_added
            - group.member_removed
            - group.updated
            - flag.created
            - flag.deleted
            - flag.updated
            - flag.rule_updated
            - invitation.accepted
            - invitation.created
            - invitation.resent
            - invitation.revoked
            - magic_auth.created
            - organization.created
            - organization.deleted
            - organization.updated
            - organization_domain.created
            - organization_domain.deleted
            - organization_domain.updated
            - organization_domain.verified
            - organization_domain.verification_failed
            - password_reset.created
            - password_reset.succeeded
            - user.created
            - user.updated
            - user.deleted
            - organization_membership.created
            - organization_membership.deleted
            - organization_membership.updated
            - role.created
            - role.deleted
            - role.updated
            - organization_role.created
            - organization_role.deleted
            - organization_role.updated
            - permission.created
            - permission.deleted
            - permission.updated
            - session.created
            - session.revoked
            - waitlist_user.approved
            - waitlist_user.created
            - waitlist_user.denied
          example:
          - user.created
          - dsync.user.created
      required:
      - endpoint_url
      - events
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: 'Your WorkOS API key prefixed with `sk_`. Pass it as a Bearer token: `Authorization: Bearer sk_example_123456789`.'
    access_token:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: An SSO access token returned from the Get a Profile and Token endpoint.