> ## Documentation Index
> Fetch the complete documentation index at: https://jetemail.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a webhook

> Creates a new webhook configuration. A signing secret will be automatically generated.



## OpenAPI

````yaml /openapi.json post /webhooks
openapi: 3.0.0
info:
  title: JetEmail API
  version: 1.0.0
  description: API documentation for JetEmail's transactional email service.
servers:
  - url: https://api.jetemail.com
    description: Production
security:
  - apiKeyAuth: []
externalDocs:
  description: Download OpenAPI Specification
  url: /openapi.json
paths:
  /webhooks:
    post:
      tags:
        - Webhooks
      summary: Create a webhook
      description: >-
        Creates a new webhook configuration. A signing secret will be
        automatically generated.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - url
                - events
              properties:
                name:
                  type: string
                  maxLength: 64
                  pattern: ^[a-zA-Z0-9-_\s]+$
                  description: >-
                    Human-readable webhook name. Only letters, numbers, hyphens,
                    underscores, and spaces allowed.
                  example: Production Webhook
                url:
                  type: string
                  format: uri
                  description: Webhook endpoint URL (must be http or https)
                  example: https://example.com/webhook
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - outbound.delivered
                      - outbound.bounced
                      - outbound.rejected
                      - outbound.deferred
                      - outbound.spam
                      - outbound.dropped
                      - outbound.virus
                      - outbound.opened
                      - outbound.clicked
                      - outbound.complaint
                      - inbound.received
                      - inbound.delivered
                      - inbound.spam
                      - inbound.blocked
                  minItems: 1
                  description: >-
                    List of event types to subscribe to. Must only include
                    allowed event types.
                  example:
                    - outbound.delivered
                    - outbound.bounced
                    - inbound.received
                status:
                  type: integer
                  enum:
                    - 0
                    - 1
                  default: 1
                  description: 'Webhook status: 0 = disabled, 1 = enabled'
                  example: 1
                filter_users:
                  type: array
                  items:
                    type: string
                  nullable: true
                  description: >-
                    Filter outbound events by username. Must be transactional
                    keys or smarthosts you own. (null = all)
                  example: null
                filter_domains:
                  type: array
                  items:
                    type: string
                  nullable: true
                  description: >-
                    Filter inbound events by domain. Must be inbound domains you
                    own. (null = all)
                  example:
                    - example.com
            examples:
              Basic Webhook:
                value:
                  name: My Webhook
                  url: https://example.com/webhook
                  events:
                    - outbound.delivered
                    - outbound.bounced
              Webhook with Filters:
                value:
                  name: Production Webhook
                  url: https://example.com/webhook
                  events:
                    - outbound.delivered
                    - outbound.bounced
                    - inbound.received
                  status: 1
                  filter_domains:
                    - example.com
                    - test.com
      responses:
        '200':
          description: Webhook created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Webhook created successfully
                  webhook:
                    type: object
                    properties:
                      uuid:
                        type: string
                        format: uuid
                        description: Unique webhook UUID
                        example: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                      name:
                        type: string
                        description: Human-readable webhook name
                        example: Production Webhook
                      url:
                        type: string
                        example: https://example.com/webhook
                      secret:
                        type: string
                        description: >-
                          The webhook signing secret. Store this securely - it
                          will not be shown again.
                        example: whsec_abc123def456...
                      events:
                        type: array
                        items:
                          type: string
                          enum:
                            - outbound.queued
                            - outbound.delivered
                            - outbound.bounced
                            - outbound.rejected
                            - outbound.deferred
                            - outbound.spam
                            - outbound.dropped
                            - outbound.virus
                            - outbound.opened
                            - outbound.clicked
                            - outbound.complaint
                            - inbound.received
                            - inbound.delivered
                            - inbound.spam
                            - inbound.blocked
                        example:
                          - outbound.delivered
                          - outbound.bounced
                      status:
                        type: string
                        example: enabled
                      filter_users:
                        type: array
                        items:
                          type: string
                        nullable: true
                        example: null
                      filter_domains:
                        type: array
                        items:
                          type: string
                        nullable: true
                        example: null
                      created_at:
                        type: integer
                        example: 1736524800
                      last_modified:
                        type: integer
                        example: 1736524800
        '400':
          description: Bad request - Invalid input
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: URL is required and must be a string
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: User information not found
        '403':
          description: >-
            Forbidden - Invalid filter values (users/domains not owned by
            caller)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: >-
                      Invalid filter_domains: example.com. You can only filter
                      by domains that you own.
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Failed to create webhook
components:
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      description: API key for account management endpoints. Use your api_ prefixed token.

````