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

# Create Webhook

> Create a new webhook to receive event notifications at the specified URL.



## OpenAPI

````yaml POST /webhooks
openapi: 3.1.0
info:
  title: Lettr API
  version: 1.0.0
  description: >-
    Lettr Email API - Send transactional emails with tracking, attachments, and
    personalization.
  contact:
    name: Lettr Support
    url: https://lettr.com
  license:
    name: Proprietary
    url: https://lettr.com/terms
servers:
  - url: https://app.lettr.com/api
    description: Production
security: []
tags:
  - name: Emails
    description: Email sending operations
  - name: Templates
    description: Email template management operations
  - name: Domains
    description: Domain management operations
  - name: Webhooks
    description: Webhook management operations
  - name: Audience
    description: 'Audience management: lists, contacts, topics, properties, and segments'
  - name: Campaigns
    description: >-
      Campaign operations: listing, stats, engagement events, and
      dispatch/scheduling
paths:
  /webhooks:
    post:
      tags:
        - Webhooks
      summary: Create Webhook
      description: >-
        Create a new webhook to receive event notifications at the specified
        URL.
      operationId: storeWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreWebhookRequest'
            example:
              name: Order Notifications
              url: https://example.com/webhook
              auth_type: basic
              auth_username: user
              auth_password: secret
              events_mode: selected
              events:
                - message.delivery
                - message.bounce
      responses:
        '201':
          description: Webhook created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreWebhookResponse'
              example:
                message: Webhook created successfully.
                data:
                  id: webhook-abc123
                  name: Order Notifications
                  url: https://example.com/webhook
                  enabled: true
                  event_types:
                    - message.delivery
                    - message.bounce
                  auth_type: basic
                  has_auth_credentials: true
                  last_successful_at: null
                  last_failure_at: null
                  last_status: null
        '400':
          description: Bad request - SparkPost rejected the webhook configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Invalid webhook configuration.
                error_code: send_error
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: Conflict - A webhook with this target URL already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: A webhook with this target URL already exists.
                error_code: resource_already_exists
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          description: Server error - Failed to create webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Failed to create webhook. Please try again later.
                error_code: send_error
      security:
        - bearerAuth: []
components:
  schemas:
    StoreWebhookRequest:
      type: object
      description: Request body for creating a webhook
      required:
        - name
        - url
        - auth_type
        - events_mode
      properties:
        name:
          type: string
          description: Name of the webhook
          maxLength: 255
          example: Order Notifications
        url:
          type: string
          format: uri
          description: URL where webhook events will be sent
          maxLength: 2048
          example: https://example.com/webhook
        auth_type:
          type: string
          enum:
            - none
            - basic
            - oauth2
          description: Authentication type for the webhook
          example: basic
        auth_username:
          type: string
          description: >-
            Username for basic authentication (required when auth_type is
            'basic')
          maxLength: 255
          example: user
        auth_password:
          type: string
          description: >-
            Password for basic authentication (required when auth_type is
            'basic')
          maxLength: 255
          example: secret
        oauth_client_id:
          type: string
          description: OAuth2 client ID (required when auth_type is 'oauth2')
          maxLength: 255
        oauth_client_secret:
          type: string
          description: OAuth2 client secret (required when auth_type is 'oauth2')
          maxLength: 255
        oauth_token_url:
          type: string
          format: uri
          description: OAuth2 token URL (required when auth_type is 'oauth2')
          maxLength: 2048
        events_mode:
          type: string
          enum:
            - all
            - selected
          description: Whether to receive all events or only selected ones
          example: selected
        events:
          type: array
          description: >-
            List of event types to receive (required when events_mode is
            'selected'). Fully-prefixed names such as `message.delivery` are
            canonical; short names (`delivery`) and the legacy `engagament.*`
            prefix are accepted for backwards compatibility and are normalised
            to the fully-prefixed form.
          items:
            type: string
            enum:
              - message.injection
              - message.delivery
              - message.bounce
              - message.delay
              - message.out_of_band
              - message.spam_complaint
              - message.policy_rejection
              - engagement.click
              - engagement.open
              - engagement.initial_open
              - engagement.amp_click
              - engagement.amp_open
              - engagement.amp_initial_open
              - generation.generation_failure
              - generation.generation_rejection
              - unsubscribe.list_unsubscribe
              - unsubscribe.link_unsubscribe
              - relay.relay_injection
              - relay.relay_rejection
              - relay.relay_delivery
              - relay.relay_tempfail
              - relay.relay_permfail
          example:
            - message.delivery
            - message.bounce
    StoreWebhookResponse:
      type: object
      description: Response after creating a webhook
      required:
        - message
        - data
      properties:
        message:
          type: string
          description: Human-readable response message
          example: Webhook created successfully.
        data:
          $ref: '#/components/schemas/WebhookView'
    ErrorResponse:
      type: object
      required:
        - message
        - error_code
      description: Error response for non-validation errors (400, 409, 500, 502).
      properties:
        message:
          type: string
          description: Human-readable error message
          example: The sender domain could not be determined from the email address.
        error_code:
          $ref: '#/components/schemas/ErrorCode'
    WebhookView:
      type: object
      description: View of a webhook
      required:
        - id
        - name
        - url
        - enabled
        - auth_type
        - has_auth_credentials
      properties:
        id:
          type: string
          description: Unique identifier for the webhook
          example: webhook-abc123
        name:
          type: string
          description: Name of the webhook
          example: Order Notifications
        url:
          type: string
          format: uri
          description: URL where webhook events will be sent
          example: https://example.com/webhook
        enabled:
          type: boolean
          description: Whether the webhook is enabled
          example: true
        event_types:
          type:
            - array
            - 'null'
          description: Specific event types the webhook receives (null if all events)
          items:
            type: string
          example:
            - message.delivery
            - message.bounce
        auth_type:
          type: string
          description: Authentication type for the webhook (none, basic, oauth2)
          example: basic
        has_auth_credentials:
          type: boolean
          description: Whether authentication credentials are configured
          example: true
        last_successful_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Timestamp of the last successful webhook delivery
          example: '2024-01-15T10:30:00+00:00'
        last_failure_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Timestamp of the last failed webhook delivery
          example: null
        last_status:
          type:
            - string
            - 'null'
          description: Status of the last delivery attempt (success or failure)
          enum:
            - success
            - failure
            - null
          example: success
    ErrorCode:
      type: string
      description: >-
        Error codes returned by the API.


        | Code | HTTP Status | Description |

        |------|-------------|-------------|

        | `validation_error` | 422 | Request validation failed. Check the
        `errors` object for field-specific messages. |

        | `invalid_domain` | 400 | The sender domain could not be determined
        from the email address. |

        | `unconfigured_domain` | 400 | The sender domain is not configured or
        approved for sending. |

        | `send_error` | 400, 500 | General error during email send preparation
        or domain registration. |

        | `retrieval_error` | 400, 500 | Failed to retrieve resources (e.g.,
        sandbox key without associated user, upstream error). |

        | `transmission_failed` | 502 | Email transmission to the upstream
        provider failed. |

        | `resource_already_exists` | 409 | The resource (e.g., domain) already
        exists. |

        | `not_found` | 404 | The specified resource was not found. |

        | `template_not_found` | 404 | The specified template, project, or
        template version was not found. |

        | `insufficient_scope` | 403 | The API key does not have the required
        scope for this endpoint. |

        | `schedule_cancellation_failed` | 409, 500 | Could not cancel the
        scheduled transmission (already sent or upstream error). |

        | `quota_exceeded` | 429 | Monthly sending quota exceeded. Upgrade your
        plan to continue sending. |

        | `daily_quota_exceeded` | 429 | Daily sending quota exceeded. Try again
        tomorrow. |

        | `campaign_not_sendable` | 422 | The campaign cannot be sent in its
        current state (not a draft, or missing subject/sender/content). |

        | `campaign_not_scheduled` | 422 | The campaign is not scheduled, so it
        cannot be unscheduled. |
      enum:
        - validation_error
        - invalid_domain
        - unconfigured_domain
        - send_error
        - retrieval_error
        - transmission_failed
        - resource_already_exists
        - not_found
        - template_not_found
        - insufficient_scope
        - schedule_cancellation_failed
        - quota_exceeded
        - daily_quota_exceeded
        - campaign_not_sendable
        - campaign_not_scheduled
      example: invalid_domain
    UnauthorizedResponse:
      type: object
      required:
        - message
      description: Error response for authentication failures (401).
      properties:
        message:
          type: string
          description: Human-readable error message
          example: API key is required.
    ValidationErrorResponse:
      type: object
      required:
        - message
        - error_code
        - errors
      properties:
        message:
          type: string
          description: Human-readable error message
          example: Validation failed.
        error_code:
          type: string
          description: Error code (always `validation_error` for 422 responses)
          const: validation_error
          example: validation_error
        errors:
          type: object
          description: Field-specific validation errors
          additionalProperties:
            type: array
            items:
              type: string
          example:
            from:
              - The sender email address is required.
            to:
              - At least one recipient email address is required.
  responses:
    UnauthorizedError:
      description: Unauthorized - Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedResponse'
          examples:
            missing_key:
              summary: Missing API key
              value:
                message: API key is required.
            invalid_key:
              summary: Invalid API key
              value:
                message: Invalid API key.
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key for authentication

````